Games of Daze

home *** CD-ROM | disk | FTP | other *** search

/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / utils / alch18 / manual.exe / ALCHEMY.DOC

Wrap

Text File | 1994-04-15 | 448KB | 13,697 lines

Image Alchemy Version 1.7 Handmade Software, Inc. Notice Handmade Software, Inc. makes no warranty of any kind either expressed or implied. In particular we make no warranty as to merchantability or fitness for a particular purpose. In no event shall Handmade Software, Inc. be liable for any errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of the Image Alchemy product or documentation. This document contains proprietary information which is protected by copyright. No part of this document may be photocopied, reproduced, or translated without the prior written consent of Handmade Software, Inc. The information in this document is subject to change without notice. Copyright Copyright (c) 1990-1994 Handmade Software, Inc., Fremont, California All Rights Reserved Copyright (c) 1990-1994 Handmade Software, Inc. ii Image Alchemy was written by: Marcos H. Woehrmann Allan N. Hessenflow David Kettmann Paul H. Yoshimune Handmade Software, Inc. 48820 Kato Road, Suite 110 Fremont, CA 94538 1 800 358 3588 +1 510 252 0101 +1 510 252 0909 fax +1 510 252 0929 BBS Internet: hsi@netcom.COM CompuServe: 71330, 3136 Copyright (c) 1990-1994 Handmade Software, Inc. iii Trademarks Image Alchemy is a trademark of Handmade Software, Inc. All other products or services mentioned in this manual, including: IBM PC, IBM PC AT, 80286, 80386, 80486, VGA, 8514/A, Paradise, Everex, Trident, Video 7, Tseng Labs, Western Digital, MS- DOS, PC-DOS, SPARC, Sun, SPARCstation, SPARCserver, SunOS, Targa, PostScript, EPS, Encapsulated PostScript, GIF, ILBM, IFF, Macintosh, Silicon Graphics, SGI, PCX, TIFF, Windows, Windows BitMaP, EGA, PCL, HP, AI, PS/2, HAM, PC Paintbrush, MacBinary, PHIPS, NeXT, C- Cube, Storm Technology, Radius, ColorSqueeze, VFCtool, Amiga, CompuServe, LaserJet, Times Roman, and Gill Sans are trademarks, registered trademarks, service marks, or registered service marks of their respective companies or organizations. Even though they are never mentioned in this document, you should know that Yellow Pages is a registered trademark in the United Kingdom of British Telecommunications plc., and may also be a trademark of various telephone companies around the world. iv Copyright (c) 1990-1994 Handmade Software, Inc. Contents ------------------------------------------------------------------------ Chapter 0 Introduction............................................1 About This Manual.......................................2 Document Conventions....................................3 Chapter 1 Installation Introduction............................................5 Image Alchemy for MS-DOS Required Equipment....................................6 Optional Equipment....................................7 Packing List..........................................7 Installation Instructions.............................8 Environment Variables.................................8 UNIX Installation Required Equipment...................................17 Packing List.........................................17 Installation Instructions............................17 Environment Variables................................18 Differences between UNIX and MS-DOS..................19 Chapter 2 Introduction Basic Instructions.....................................21 Limitations on filenames...............................23 Output Path............................................23 Using Response Files...................................24 Multiple Runs of Alchemy...............................26 Chapter 3 Graphical User Interface (MS-DOS only) Introduction...........................................29 Starting the GUI.......................................29 The Main Screen........................................30 Quitting the GUI.......................................31 The File Sub-Menu......................................31 The Resize Sub-Menu....................................34 The Palette Sub-Menu...................................34 The Colors Sub-Menu....................................34 The Dither Sub-Menu....................................35 Chapter 4 Output Options Introduction...........................................37 Copyright (c) 1990-1994 Handmade Software, Inc. v Identifying Image Files................................39 MacBinary..............................................39 Other Information......................................39 Image File Formats ADEX.................................................41 Adobe Acrobat PDF....................................42 Alpha Microsystems BMP...............................44 Autologic............................................45 AVHRR................................................46 Binary Information File (BIF)........................48 Calcomp CCRF.........................................50 CALS.................................................52 Core IDC.............................................53 Cubicomp PictureMaker................................55 Dr. Halo CUT.........................................57 Encapsulated PostScript..............................58 ER Mapper Raster.....................................61 Erdas LAN/GIS........................................63 First Publisher ART..................................66 Freedom of Press.....................................67 GEM VDI Image File...................................69 GIF..................................................71 GOES.................................................73 Hitachi Raster Format................................75 HP Printer Command Language (PCL)....................76 HP Raster Transfer Language (RTL)....................80 HP-48sx Graphic Object (GROB)........................84 HSI JPEG.............................................85 HSI Palette..........................................86 HSI Raw..............................................87 IBM Picture Maker....................................88 IFF/ILBM.............................................89 Img Software Set.....................................90 Jovian VI............................................91 JPEG/JFIF............................................92 Lumena CEL...........................................95 Macintosh PICT/PICT2.................................96 MacPaint.............................................98 MTV Ray Tracer.......................................99 Multi-Image Palette.................................100 OS/2 Bitmap.........................................102 PCPAINT/Pictor Page Format..........................103 PCX.................................................105 PDS.................................................108 Portable BitMap (PBM)...............................110 Puzzle..............................................112 Q0..................................................113 QDV.................................................114 QRT Raw.............................................115 RIX.................................................116 Scodl...............................................117 Silicon Graphics Image..............................120 SPOT Image..........................................121 Stork...............................................123 vi Copyright (c) 1990-1994 Handmade Software, Inc. Sun Icon............................................125 Sun Raster..........................................126 Targa...............................................128 TIFF................................................130 Utah Raster Toolkit.................................132 VITec...............................................134 Vivid...............................................135 Windows Bitmap......................................136 WordPerfect Graphic File............................139 XBM.................................................140 XPM.................................................142 XWD.................................................145 Chapter 5 General Options Introduction..........................................147 Conserve Memory.......................................148 Display Image Stats...................................149 Do Not Alter Output Filename..........................150 Help..................................................151 Override Input Type...................................152 Overwrite.............................................154 Program Information...................................155 Quiet.................................................156 Warnings..............................................157 Wildcard..............................................158 Chapter 6 Colour and Palette Options Introduction..........................................161 Black and White.......................................162 Colours...............................................163 Dither................................................165 EGA Palette...........................................167 False Colour..........................................168 Gamma Correction......................................169 Match Palette.........................................171 Negate................................................173 Palette...............................................174 Palette Selection.....................................176 Spiff.................................................178 True Colour (15 bits).................................180 True Colour (16 bits).................................181 True Colour (24 bits).................................182 True Colour (32 bits).................................184 Undercolour Removal...................................185 Uniform Palette.......................................186 Chapter 7 Scaling Options Introduction..........................................189 Flip Image............................................190 Mirror Image..........................................191 Offset Image..........................................192 Preserve Aspect Ratio.................................193 Copyright (c) 1990-1994 Handmade Software, Inc. vii Scale Image Horizontally..............................194 Scale Image Vertically................................197 Specify Image Aspect Ratio............................199 Specify Image Resolution..............................201 Chapter 8 Viewing Options (MS-DOS Only) Display Hardware......................................203 Display Resolutions...................................206 Offset View...........................................207 View Image............................................208 View Image in True Colour Mode........................209 View Scaled Image.....................................211 View Scaled Image in True Colour Mode.................213 Chapter 9 Tutorial and Examples Introduction..........................................215 Appendix A Answers to Frequently Asked Questions ....................................................219 Appendix B Colour and Dithering ....................................................231 Appendix C JPEG Description ....................................................237 Appendix D Customer Support ....................................................241 Appendix E Binary Information Files (BIF) ....................................................243 Appendix F HSI Raw Files ....................................................247 Appendix G Undercolour Removal Files ....................................................253 Appendix H HSI PAL Files ....................................................257 Appendix I Acknowledgments ....................................................259 viii Copyright (c) 1990-1994 Handmade Software, Inc. Appendix J Other Useful Software ....................................................261 Glossary ....................................................277 References ....................................................281 Index Not Included in the online documentation (sorry) Copyright (c) 1990-1994 Handmade Software, Inc. ix x Copyright (c) 1990-1994 Handmade Software, Inc. 0 Introduction to Image Alchemy ------------------------------------------------------------------------ What is Image Image Alchemy is a software utility that Alchemy? manipulates computer image files. Primarily, Image Alchemy converts between various graphics file formats. Image Alchemy can translate between a large variety of file formats including industry standards such as GIF and TIFF as well as vendor-specific file formats such as Sun Raster and Scodl. Currently Alchemy supports over 60 different formats, and new formats are always being added; in fact, our goal is to have Image Alchemy be able to read and write every image file format in the world. Image Alchemy can also resize an image, change the number of colours in an image, change an image from colour to black and white, and change the colour space an image uses. Finally, Image Alchemy performs JPEG compression. This is a standard for image compression that can achieve much higher compression ratios than conventional compression techniques. For further information see Appendix C, "What is JPEG Compression". Copyright (c) 1990-1994 Handmade Software, Inc. 1 About this manual This manual is divided into 12 chapters, 11 appendices, a glossary, references, a colophon, and an index. Chapter 0 Introduction and Conventions Chapter 1 Installation Instructions Chapter 2 Introduction to Alchemy Chapter 3 Graphical User Interface (MS-DOS only) Chapter 4 Output Options Chapter 5 General Options Chapter 6 Colour and Palette Options Chapter 7 Scaling Options Chapter 8 Viewing Options (MS-DOS only) Chapter 9 Tutorial and Examples Appendix A Answers to Frequently Asked Questions Appendix B Colour and Dithering Appendix C JPEG Description Appendix D Customer Support Appendix E Binary Information Files (BIF) Appendix F HSI Raw Files Appendix G Undercolour Removal Files Appendix H PAL Files Appendix I Acknowledgments Appendix J Other Useful Software Glossary References Colophon Index 2 Copyright (c) 1990-1994 Handmade Software, Inc. Document Type style Used for conventions italic Parameters. You supply values for the items shown in italic. For example, if the description of a command includes filename, you would type in the name of the desired file. [ ] Brackets. Indicate optional items. ... Ellipses. Indicates a list of items or items which may be repeated. fixedspace Examples of Alchemy usage which can be typed in exactly as written. Many of the examples give file names which probably don't exist on your system; substitute different file names as appropriate. Copyright (c) 1990-1994 Handmade Software, Inc. 3 4 Copyright (c) 1990-1994 Handmade Software, Inc. 1 Installing Image Alchemy ------------------------------------------------------------------------ Overview Installation of Image Alchemy is straightforward; it involves copying the Alchemy program and support files off of the supplied floppy disks or tape onto your hard drive or network and setting some environment variables. Copyright (c) 1990-1994 Handmade Software, Inc. 5 Image Alchemy for MS-DOS ------------------------------------------------------------------------ Required At a minimum you must have the following hardware equipment and software to run Image Alchemy. Computer An MS-DOS computer equipped with an 80286, 80386, 80486, Pentium, or better Intel processor. Many of the conversions that Alchemy does are CPU intensive, so a faster computer is definitely an advantage. Memory At least 400k of free memory. Some conversions and some images require more memory (Alchemy will attempt to use all available system memory, so if you get out-of-memory errors or warnings try removing as many resident programs as you can (also, installing MS-DOS 5.0, MS-DOS 6.0, or a 3rd party memory manager such as 386MAX or QEMM will free up more memory)). Alchemy makes use of extended and expanded memory while performing conversions. This can greatly speed up the conversion process. In general you will need as much memory as the size of the image, in pixels, being converted. For example, a 640x480 true colour image will use 900k of memory. Hard drive A hard drive with at least as much free space as four times the size of the image being converted (i.e. a 640x480 image will require up to 1.2 megabytes of free space). Operating system MS-DOS or PC-DOS 3.x or greater (because of the additional free memory available, use of MS-DOS 5.0 or higher is recommended). Optional The following hardware is optional. equipment Display A supported SVGA, 8514/A, or XGA board, if you wish to view images. Supported SVGA boards include those with a VESA driver or with the Paradise, Everex, Trident, Video 7, ATI, Ahead, NCR, or Tseng Labs chipsets. 6 Copyright (c) 1990-1994 Handmade Software, Inc. Supported 8514/A boards include IBM and those with the Western Digital chipset. Supported XGA boards include those from IBM. Math co-processor A math co-processor will increase the spead of raster scaling types c and d. Packing list The enclosed diskettes contain the following files: INSTALL.EXE The Image Alchemy installation program. ALCHEMY.EXE The Image Alchemy software. GUI.EXE The Image Alchemy graphical- user-interface (menu system). READ.ME A text document describing any last minute revisions. \SAMPLES A directory containing sample data files and images. See the READ.ME2 file in this directory for further information. Environment Alchemy uses several different environment variables and variables to determine its behavior. These config.sys control, among other things, how Image Alchemy uses extended or expanded memory, which display resolutions are available for image viewing, and where temporary files are stored. path You must either add c:\alchemy to your path, copy the alchemy.exe file to a directory which is already in your path, or be in the c:\alchemy directory when executing Alchemy. Copyright (c) 1990-1994 Handmade Software, Inc. 7 Temporary disk Alchemy uses the environment variable TMP to files determine where to open its temporary files. If you have a big enough RAM drive you may want to specify it using the TMP variable. Be aware that Alchemy needs up to 4 times as much space on that drive as the size of the image (a 640 by 480 image requires up to 1.2 megabytes). An example of setting the TMP variable to the \temp directory on drive e: would be set TMP=e:\temp. Use of extended If there is enough extended or expanded memory and expanded available, Alchemy will use it instead of some of memory the temporary files it would otherwise use during some conversions. To use extended memory you must have an XMS driver installed in the config.sys file (such as HIMEM.SYS, QEMM, or 386MAX). To use expanded memory you must have a LIM 3.2 or LIM 4.0 expanded memory driver installed (such as EMM386, QEMM, or 386MAX). Alchemy's use of extended/expanded memory can be disabled. To disable the use of extended and expanded memory, set the environment variable alchemy to x (type set alchemy=x at the DOS prompt). The availability of extended or expanded memory will not allow you to convert larger images, it will just increase the speed of conversions. If you need to convert very large images contact us about upgrading to Alchemy/386, the 386 Enhanced version of Image Alchemy. Checking for Alchemy will normally check to determine if there 8514/A boards is an 8514/A board installed in the computer when viewing images. However, this can interfere with some network boards, as they use the same I/O addresses that 8514/A boards use. To disable 8514/A checking, set the environment variable alchemy to 8 (type set alchemy=8 at the DOS prompt). Note that this can be combined with other options; for example, to disable both 8514/A checking and extended/expanded memory usage, use set alchemy=8x. 8 Copyright (c) 1990-1994 Handmade Software, Inc. Limiting maximum Alchemy will automatically choose the lowest display resolution which will fit the entire image when resolution viewing images without specifying a display resolution with a VESA compatible SVGA board. However, depending on the monitor and SVGA board combination you have, this can be bad since the monitor may not support the particular resolution the SVGA board is trying to switch to. To avoid this problem, the environment variable alchemy may be set to indicate the maximum display resolution which Alchemy should use. Set the alchemy variable to the highest horizontal resolution which your monitor is capable of. Valid values are 1280, 1024, 800, and 640. For example, type set alchemy=800 at the DOS prompt if your monitor only supports 640x480 mode and 800x600 mode. Combining options To disable extended/expanded memory usage, and limit the viewing resolution to 640x480 use set alchemy=x640. Copyright (c) 1990-1994 Handmade Software, Inc. 9 UNIX Installation ------------------------------------------------------------------------ Required At a minimum you must have the following hardware equipment to run Image Alchemy. Disk space A hard drive with at least 2 megaybtes of free space for the Alchemy software and four times as much free space as the size of the image being converted (i.e. a 640x480 image will require up to 1.2 megabytes of free space). Packing list The enclosed diskette or tape is in tar format and contains the following files: alchemy The Alchemy software. read.me A text document describing any last minute revisions. /samples A directory containing sample data files and images. See the read.me2 file in this directory for further information. Environment Alchemy uses an environment variable to determine variable usage where to place temporary files. path You must either add $HOME/alchemy to your path, copy the file alchemy to a directory which is already in your path, or be in the $HOME/alchemy directory when executing Alchemy. Temporary disk Alchemy uses the environment variable TMPDIR to files determine where to put its temporary files. This is usually set to /usr/tmp or /tmp, but if you are converting very large images there may not be enough space available in the partition those directories are on (for example, converting a 10000 x 10000 pixel 24 bit colour image can require up to 300 megabytes of free disk space for temporary file storage). 10 Copyright (c) 1990-1994 Handmade Software, Inc. If there is not enough space in the usual TMPDIR directory you will need to set the environment variable TMPDIR to a directory on a different partition. For example, to set the temporary file directory to the directory /home/images use setenv TMPDIR /home/images. Contact your system administrator if you have problems with Alchemy running out of disk space while converting images. Differences The UNIX and MS-DOS versions of Image Alchemy are between UNIX and very similar. However, there are several MS-DOS important differences between the two versions: Pathnames Because the MS-DOS and UNIX operating systems use different conventions for path names, users of UNIX will have to substitute forward slashes, "/", for the back slashes, "\", found in the examples in this manual. Unintentional UNIX users should also be aware that the UNIX wildcard shell they are using may be performing wildcard expansion expansion on certain characters (generally "*" and "?"). Since these are options which Alchemy uses, they need to be escaped to prevent the wildcard substitution. This is done by using a back slash, "\", before the character (so -? becomes -\?). Sending output Several of the examples show output being sent directly to directly to a device (for example prn:). UNIX devices users cannot send output directly to a device using Image Alchemy and should substitute a file name for the output device name. Viewing images The UNIX command line version of Image Alchemy does not support image viewing at this time. We do have an OpenLook version of Image Alchemy available for Sun SPARC workstations, and are working on Motif versions for other workstations. Please contact us for information on the availability of these versions or upgrading . Copyright (c) 1990-1994 Handmade Software, Inc. 11 12 Copyright (c) 1990-1994 Handmade Software, Inc. 2 Introduction ------------------------------------------------------------------------ Introduction Image Alchemy is a command-line driven program. Basic The basic Image Alchemy usage instructions are: instructions alchemy inputFileName [outputFileName] [output PathName] -options ... Options Options are the commands that you give Alchemy so that it knows what you want it to do. So that Alchemy can distinguish between options and file names on the command line, options are preceded by a dash ("-"). The only option that is required is the output file format. Image Alchemy will make reasonable decisions for all of the other options. Some options take parameters. The parameters may immediately follow the option or be separated by a space. For example, either -c128 or -c 128 is acceptable. The options themselves are documented in Chapters 3 through 8. Note that options can appear anywhere in the command line and usually they can be in any order (certain options take parameters; in those cases the parameters must follow the option). The case of the options is significant. For example, -d and -D mean different things. InputFileName The inputFileName is the file name of the existing image file that you are converting from or viewing and must be specified. The inputFileName may include an optional drive and/or path. Copyright (c) 1990-1994 Handmade Software, Inc. 13 OutputFileName The outputFileName is the name of the file you are converting the image to. The outputFileName is optional; if it is not specified Alchemy generates one by substituting an appropriate extension to the input file name. If you specify an outputFileName and it does not include an extension one will be added. The outputFileName may include an optional drive and/or path. If you do not supply a path the current directory will be used as the destination directory. The inputFileName and the outputFileName cannot be the same unless you are writing the output file to a different directory. OutputPathName The outputPathName is the location where you want to put the output that Alchemy will create. The outputPathName is optional; if it is not specified Alchemy places the output in the current directory or in the directory specified as part of the outputFileName. Specifying an outputPathName is useful when using the wildcard option to convert multiple files; see the wildcard command below for more information. Limitations on Since Alchemy lets you optionally enter a space filenames between an option and its parameter it is possible to confuse Alchemy if one of the filenames starts with a number. In particular, if you use an option which has an optional parameter, you choose not to supply the parameter, and you follow that option immediately with a filename which starts with a number, Alchemy doesn't realize that the filename is not the parameter. While it sounds unlikely that this would ever be a problem it actually happens quite often. Example If you wanted to convert the file 12.gif to a Targa file with the name output.tga you would have to be careful of the order in which you specified things. If you say alchemy -a 12.gif output.tga 14 Copyright (c) 1990-1994 Handmade Software, Inc. Alchemy would misinterpret that as alchemy -a12 .gif output.tga and would generate an error. The easiest way around this problem is to always put the filenames first, such as: alchemy 12.gif output.tga -a Output path The output path name is the location where Alchemy will place its output. While the outputPathName is usually specified on the command line as part of the outputFileName it is useful when using wildcards (and an outputFileName can not be specified). Example To convert all of the GIF files in the current directory to grayscale and place the results in the \images directory you can use the following command line: alchemy -- *.gif \images -g -b Using response Alchemy can read command line parameters from text files files (called response files). Using response files is equivalent to typing the options and/or file names on the command line. Response files are useful when you have commonly used commands or when you have long commands which would be hard to remember or exceed the command line limits of your operating system. To use a response file you create a text file containing the options and/or file names that you would ordinarily pass to Alchemy on the command line. You create this text file using a text editor. This file can have any name or extension you wish. To pass this file to Alchemy use the @ operator, followed immediately by the name of the text file. For example, if you frequently need to scale images to be no larger than 640x480, using 'b' quality scaling, and preserving aspect ratio, you can make a text file which looks like this (called scale, for purposes of this example): -Xb640 -Yb480 -+ Copyright (c) 1990-1994 Handmade Software, Inc. 15 You would then use this text file with Alchemy by passing its name along with any other options (including the output file type option and the file names). For example: alchemy @scale test.gif new.gif -g would convert the GIF file test.gif to a GIF file called new.gif, while performing the desired scaling operation. It is also possible to place filenames of images to convert and other response files in response files. For example, if you want to convert the files test1.gif, image.tga, scan1.tif, scan2.tif, and scan3.tif to JPEG files you can create a text which looks like this (called files): test1.gif image.tga scan1.tif scan2.tif scan3.tif And then use this command line to convert those files to JPEG files: alchemy -- @files -j Note the use of the -- option to indicate to Alchemy that more than one filename will be specified. For MS-DOS users it is also possible to place wildcards in response files. For example, if you want to convert all of the .gif, .tif, and .tga files to JPEG files you can create a text file which looks like this (called wild): *.gif *.tif *.tga And then use this command line to convert those files to JPEG files: alchemy -- @wild -j UNIX users can accomplish the same task by using ls and redirecting output to a file: ls *.gif *.tif *.tga >wild 16 Copyright (c) 1990-1994 Handmade Software, Inc. And then use this command line to convert those files to JPEG files (note the use of the -- option to indicate to Alchemy that you are giving it more than one file to convert): alchemy -- @wild -j If you wanted to scale the images at the same time, using the scale text file created earlier, you would add that response file to the command line. For example: alchemy -- @files @scale -j Comments A line in a response file which begins with a # is treated as a comment and ignored. Response files may contain commands and filenames on multiple lines and may also contain blank lines. Using multiple Sometimes you may know what you want to accomplish runs of Alchemy but not how to specify the correct combination of options. For example, you may wish to resize a true colour Targa file that you have scanned and convert it to a 16 colour GIF file. Let's say that the input file name is file.tga and you want to generate a file with the name file.gif. In this case you could use: alchemy file.tga -Xb640 -Yb480 -c16 -g However, there would be no penalty in quality if you did things in two steps: alchemy file.tga temp.raw -Xb640 -Yb480 -r alchemy temp.raw file.gif -c16 -g In this case you are telling Alchemy to use a temporary raw file called temp.raw. Except for having to delete the file temp.raw, this would give you identical results to doing things in one step. However, the order of steps is important in many cases. For example, reversing the order of the two operations in the previous example: alchemy file.tga temp.raw -c16 -g alchemy temp.raw file.gif -Xb640 -Yb480 -g Copyright (c) 1990-1994 Handmade Software, Inc. 17 would give different results. This is because the scaling operation has to temporarily convert the image to true colour, but the GIF file you are generating has to be paletted, so the second operation would re-dither the image, lowering the quality. Illegal Sometimes you will have to perform operations combinations of using multiple steps because there are some options combinations of options that Alchemy explicitly does not allow. These combinations of options are not allowed because the results would not be what you expect. For example, using the spiff option, -S, in combination with the false colour option, -F, would spiff the image first and then false colour it, which would give the same results as just using the false colour option. Since this is not the result you would most likely want, Alchemy will complain if you specify both of those options at the same time. In this case you could false colour the image first, generating a temporary image, and then spiff that image. 18 Copyright (c) 1990-1994 Handmade Software, Inc. 3 The Graphical User Interface (Menus) MS-DOS Only ------------------------------------------------------------------------ Introduction Image Alchemy v1.7 is the first release to incorporate a Graphical User Interface (also referred to as a GUI, pronounced "gooey"), commonly referred to as a menu system. The GUI can make using Alchemy much easier for casual or infrequent users, since the various command-line arguments do not need to be memorized. The GUI is actually a separate program which gets information about the conversion from the user, builds a command line for Alchemy, and then calls the actual Alchemy program. The GUI will let you view the command line parameters it uses, so that you can learn more about Alchemy itself and the options it requires to perform various conversions. Starting the GUI After installing Image Alchemy (described in Chapter 1), the Alchemy executable as well as the GUI should be on your working drive. The GUI will be able to find the Alchemy executable as long as it is in either the current directory or the search path. Assuming the path has been correctly set, simply typing 'gui' will start Alchemy's graphical user interface. The Main Screen Upon starting the GUI, the screen will be mostly blank, except for a menu bar across the top of the screen, and two small windows at the bottom informing you of the currently selected input file and the output file type. Copyright (c) 1990-1994 Handmade Software, Inc. 19 If you have a mouse connected to your system, you can point-and-click through the menuing system, rather than using the keyboard. Clicking an entry on the menu bar will pull down that menu, and then clicking on a specific option will actually choose it. Alternatively, you can move the mouse cursor to the menu bar, click on a sub-menu category like File, and while continuing to hold down the mouse button, select a specific item. When you release the mouse button, that item will be chosen. To access the pull-down menu system using the keyboard, type Alt-?, where ? is the first character of the option. For example, typing Alt- F will bring down the File sub-menu, and Alt-D will bring down the Dither sub-menu. Pressing and releasing the ALT key by itself will take you up to the menu bar and pull down the first entry (the File sub-menu). The left and right arrow keys will move between the various sub-menus. At this point, the up and down arrow keys can be used to highlight a specific option; pressing Return will select that option. While in the menu system, pressing ESC will close the current menu; if you are being prompted for a value in a dialog box, ESC will abort the input, and retain the old value. As you move through various options in the sub- menus, a short help message will appear on the bottom status line, giving you further information on the option you currently have selected. Note that some sub-menu entries may be dimmed; this means that these options cannot be used at this time. This usually applies to the viewing and conversion commands, which cannot be chosen without first selecting an input file. 20 Copyright (c) 1990-1994 Handmade Software, Inc. Quitting the GUI To exit the GUI, select Quit from the File sub- menu. Alternatively, ALT-X or ALT-F4 will immediately quit the GUI without going through the menu system. The File Sub-Menu Select Input Choosing this option will bring up a listing of Image all the files in the current directory. Using either the keyboard or the mouse, you can select the input file which Alchemy will work on. There are also listings for the parent directory and various subdirectories (if any), which allow you to move around on the drive. Clicking on the Cancel button or hitting ESC will abort the selection process, keeping the previous input file name. Note that the GUI does not check to make sure that the file you have selected is a valid image file (it would slow the GUI down too much to have to open each file as you highlight it). As such, it is possible for you to select a file which Alchemy itself will not recognize when a conversion or view is requested. Select Output Selecting the Output Type will display a scrolling Type window containing the different image formats to which Alchemy can output. The up and down arrow keys will move the highlight bar up and down one item, and the PgUp and PgDn keys will move the highlight bar up and down one page. Pressing Return selects the highlighted output type. The mouse can also be used to scroll through the window; clicking on the up and down arrows will move the highlight bar up and down one entry, and clicking in the scroll bar above or below the current location marker will page up and down through the list. Copyright (c) 1990-1994 Handmade Software, Inc. 21 If you select an output format that has further options (such as compression type), a second pop- up menu will ask you to pick an option. Either typing the highlighted key or clicking on the name will select that option. For more information on the output types available, and the options that each has, see Chapter 6. Image Stats After selecting an input file, selecting this option will display various information for that file, including the height and width, number of colours, and compression ratio. Other values may be displayed, if they are available, such as dots per inch (DPI), aspect ratio, and gamma. Viewing The next four options are for viewing the image you have selected. See Chapter 9 for more information on the type of SVGA cards supported and details of the viewing commands. View Image will do a standard 8-bit view on an SVGA monitor, displaying only the center portion of the image if it exceeds maximum screen resolution. Using the View Scaled option will work similarly, except it will use Nearest Neighbor scaling to make sure the entire image fits on the screen. If you have an SVGA board and monitor capable of displaying images in true colour (15-, 16-, or 24- bits), select View True Color to take advantage of this. This option will try to view in the highest resolution possible, while displaying as much of the image as possible. If you have an image larger than what your card/monitor can display in true colour, using the View True Color Scaled option will scale the image so you can view the entire image in true colour. Show Command Line Choosing this option will display the parameters which will actually be passed to Alchemy if the Convert! entry is chosen. This allows you to see what parameters need to be passed to Alchemy on the command line to enable various options. 22 Copyright (c) 1990-1994 Handmade Software, Inc. Basic/Expert This menu entry will change, depending on the Menus current status of the menu system. When first started, the GUI will default to Basic mode, which will hide many of the more obscure options Alchemy deals with. Choosing this option will then force the GUI to use the full, more advanced menus which include all possible options. When the Expert menus are being used, choosing this option will switch back to the Basic menu system. Convert! This should be the last option you select when converting an image; use it only after you have selected all the options you need from the various other menus. After choosing this option, you will be prompted for an output filename, with a default given based on the output type chosen. To accept this filename, simply press Return. You may of course modify the default by typing different names, drives, or directories. The GUI will then generate a command line and run the Alchemy software, passing along information about the various options you have selected in the menu. A progress dialog box will keep you informed of the status of the conversion. After the conversion you will be returned to the main screen. If the conversion generates an error it will be displayed in a dialog box. Quit This option will end your GUI session, and return you to the DOS prompt. The Resize The options in this sub-menu allow you to control Sub-Menu various aspects of the output image concerning its size and DPI information. Along with being able to specify a certain image size, you can also tell Alchemy to make an image larger or smaller by some factor. Finally, you can specify the aspect ratio and DPI information from within this menu. For further information about the scaling options, see Chapter 9. Copyright (c) 1990-1994 Handmade Software, Inc. 23 The Palette Sub- The entries in the palette sub-menu allow you to Menu control various aspects of the palette and its generation, including using Heckbert's algorithm, a uniform palette, or a black and white/grayscale palette. You can also tell Alchemy to use a palette from another image, or use an undercolour removal file during the conversion process. For further information about these topics, see Chapter 8. The Colors The colors sub-menu primarily allows you to Sub-Menu specify the number of colours to be used in the output file. You can also generate a photographic negative of an image, as well as spiff it using one of three different algorithms. Finally, from within this sub-menu, you can modify the input, output, and palette gamma values. For further information about the colors options, see Chapter 8. The Dither The dither menu allows you to select the Sub-Menu particular dithering algorithm to use. You can also specify whether you want a serpentine raster or some amount of perturbation; both of these options help break up visible patterns left by the dithering. For further information about the dithering options, see Chapter 8. 24 Copyright (c) 1990-1994 Handmade Software, Inc. 4 Output Options ------------------------------------------------------------------------ Introduction The one option which is always required when running Image Alchemy is the output image file type. Even if you are just re-sizing an image, or changing the number of colours in an image, Alchemy needs to know what type of image you want to create. The file types that Image Alchemy supports are listed below. In addition to the syntax required to generate the file, any known restrictions or limitations are listed. If you have trouble reading an image in one of the file formats we claim to support please contact us (see Appendix D, Customer Support). The output option consists of a single letter, followed by any options needed for the file format you are writing. The output option, like all Alchemy options, is preceded by a dash, "-". The less common output options consist of a letter preceded by two dashes, "--". Output variations Some of the output formats have several variations; in those cases you specify which variation you want with an optional letter and/or number after the output option. Example The option to generate a Windows Bitmap file is - w. There are two types of Bitmap files: uncompressed and Run-Length-Encoded (RLE). To write out an uncompressed Bitmap file use -w0; to write out an RLE Bitmap file use -w1 (the default Bitmap file is uncompressed, so a -w without any parameter following it would also generate an uncompressed Bitmap file). Note that Alchemy allows spaces between the option and parameter, so typing -w 1 would be the same as -w1. Other variations Be aware that the other options specified on the command line may also affect the type of file that is generated. Copyright (c) 1990-1994 Handmade Software, Inc. 25 Example Within the Windows Bitmap file type there are 1 bit, 4 bit, 8 bit, and 24 bit files. Alchemy always generates a file using the best match of the file type and the output image. So, in the case of Windows Bitmap files, if the output image is black and white a 1 bit file is generated. If the output image is paletted with 16 colours or less a 4 bit file is generated. If the output image is paletted with more than 16 colours an 8 bit file is generated. And if the output image is true colour a 24 bit file is generated. You can explicitly force any of these file types by using other Alchemy options. For example, if you wanted a 1 bit Windows Bitmap file you would specify -c2 -b -w. To force a 4 bit file use -c16 -w. To force an 8 bit file use -c256 -w. And to force a true colour file use -24 -w. Identifying image Image Alchemy identifies the type of file being files read by checking various magic numbers and other information that varies from format to format. Unfortunately, some formats do not have a magic number; in those cases Alchemy uses other information to guess as to the image type. It is possible for Image Alchemy to incorrectly identify an image; if this happens you can use the -= option to force Alchemy to recognize the file as a particular format (see Chapter 7 for more information on the -= option) MacBinary When reading images, Alchemy automatically recognizes and reads MacBinary II files (MacBinary files are generated when you accidentally leave MacBinary mode on when transferring a file from a Macintosh). Other information Alchemy will preserve as much information in each file as practical; this always includes the height and width of the image and the number of colours in the image. Some file types include other data, such as the name of the image, the aspect ratio of the image, the date the image was created, etc. Since most of these items are only supported by a few file formats, Alchemy discards everything but the height, width, number of colours, gamma, aspect ratio, and resolution values. 26 Copyright (c) 1990-1994 Handmade Software, Inc. Output Options The individual output options supported by Alchemy are described in alphabetical order on the following pages. The descriptions follow the template given overleaf. Copyright (c) 1990-1994 Handmade Software, Inc. 27 Name of format -option Overview of file format. Syntax Description of syntax. Parameters Brief description of the parameters. Those parameters which require a detailed explanation are further documented under the comments section below. Extensions The extensions commonly used for this image format. When multiple extensions are listed Alchemy writes files using the first one, but will check for files using all extensions (in the order listed). Some formats use more than one file per image, in that case the extension for each piece of the image is listed. Four letter extensions are skipped on MS-DOS systems. Creator The company or individual who created this image format. Please contact them for more information on the format. Used by Programs or types of software that use this image format. Variations A list of the variations supported by Image Alchemy. Limitations Any known limitations that Image Alchemy has when reading or writing this image format. Comments Miscellaneous things of which you should be aware. Related options Other Alchemy options that affect the reading or writing of this image format. Note that -8, -24 (and, for some formats, -15, -16, and -32), -c, and -b options have an effect for most image formats and are not listed explicitly. Examples Sample conversions involving this image format. 28 Copyright (c) 1990-1994 Handmade Software, Inc. ADEX --A ADEX files are used by the ADEX Corporation ChromaGraph series of graphics cards. Syntax --A compressionType Parameter compressionType: 0:None 1:Run Length Coded The default is None. Extensions .img .rle Creator ADEX Corporation Used by ADEX ChromaGraph cards. Variations 4 bit and 8 bit images. Comments Some ADEX files don't contain a palette; in those cases there's usually a second ADEX file which contains the palette to be used. To read those images that don't have palettes, use the -F false colour option to read the palette from a separate file. Related options -F False colour Example Convert the file test.gif to an uncompressed ADEX file called test.img: alchemy test.gif --A Copyright (c) 1990-1994 Handmade Software, Inc. 29 Adobe Acrobat PDF --d Adobe Acrobat PDF (Portable Document Format) files are used by Adobe Acrobat. Syntax --d compressionType Parameter compressionType: 0:None 1:Run Length 2:LZW 3:CCITT Group 3 fax 4:CCITT Group 4 fax 5:JPEG Low Quality 6:JPEG Medium Quality 7:JPEG High Quality The default is None. Extension .pdf Creator Adobe Systems Incorporated Used by Adobe Acrobat. Variations Writes 1 bit black and white, 8 bit grayscale, 8 bit paletted, and 24 bit colour images. Limitations Adobe Acrobat files can only be written, not read. CCITT Group 3 fax and Group 4 fax files are always 1 bit, black and white. Selecting either compression type will cause Alchemy to automatically convert the input image to black and white. Comments Alchemy always writes a single page PDF file; this will be changed in a future release. Example Convert the JPEG file sample.jpg to a Run Length compressed PDF file: alchemy sample.jpg --d 1 30 Copyright (c) 1990-1994 Handmade Software, Inc. Alpha Microsystems BMP -M Alpha Microsystems BMP files are used by Alpha Microsystems. Syntax -M compressionType Parameter compressionType: 0:None 1:Packed The default is None. Extension .bmp Creator Alpha Microsystems Used by Alpha Microsystems workstations. Variations Reads and writes 1, 4, 8, and 24 bit unpacked and packed (run-length encoded) RGB images. Limitations Reading and writing HLS images is not supported. Comments When reading an image without a palette Alchemy will assume the image is gray-scale. Examples Convert the GIF file, bigpict.gif, to an uncompressed Alpha Microsystems BMP file: alchemy bigpict.gif -M Do the same thing, but force a 24 bit image, and compress the image: alchemy bigpict.gif -M1 -24 Copyright (c) 1990-1994 Handmade Software, Inc. 31 Autologic --a Autologic files are black and white or gray-scale files for use with Autologic typesetting equipment. Syntax --a Extensions .gm .gm2 .gm4 Creator Autologic, Incorporated Used by Autologic typesetting equipment. Variations Graphics modes 2 (black/white) and 4 (gray-scale) are supported. Limitations Only the High Speed Interface inline format is supported. When reading, images must be preceded by a Graphics Parameter Block. Examples Convert the file input.tif to a GM4 file called output.gm4: alchemy input.tif output.gm4 --a -b Convert the file input.tif to a GM2 file called output.gm2: alchemy input.tif output.gm2 --a -b -c2 32 Copyright (c) 1990-1994 Handmade Software, Inc. AVHRR --R AVHRR files are used for satellite image data. Syntax --R outputType Parameter outputType 1:IDIDAS Uncompressed 2:IDIDAS Compressed type 1 The default is 1 (IDIDAS Uncompressed). Extension .sst Creators National Oceanic and Atmospheric Administration (NOAA) National Environmental Satellite Data Information Service (NESDIS) Used by IDIDAS SSTMAP IMGMAP Variations Reads 8 and 11 bits per pixel IDIDAS AVHRR files. Writes 11 bits per pixel IDIDAS AVHRR files. Limitations Level 1B AVHRR files will be supported at a later date; please contact us for more information. Alchemy discards all but the top 8 bits when reading 11 bit AVHRR files. When writing, the bottom 3 bits are set to 0. Any graphics information is discarded when reading the file. Since AVHRR images are always grayscale, Alchemy assumes the use of the -b and -8 options when writing an AVHRR file. Comments AVHRR images contain a lot of information which is not part of the image data. This information includes the time and date the image was captured, the satellite which captured the image, the type of instrumentation used, etc. When reading AVHRR images this information is discarded; when writing AVHRR images 0 is written for all values for which data is unavailable. Copyright (c) 1990-1994 Handmade Software, Inc. 33 Example Convert the GOES file, florida.goe, to an uncompressed IDIDAS AVHRR file: alchemy florida.goe --R1 34 Copyright (c) 1990-1994 Handmade Software, Inc. Binary Information Files (BIF) -B There are quite a few programs which produce image files which contain just pixel data. These image files do not have a header and hence do not include enough information to allow Alchemy to read them. BIF files are a method which can be used to allow Alchemy to read these images. BIF files can also be created to allow images to be read by software which expects images to be just pixels. Since required information, such as the height and width of the image, are not present in these files - you must supply it. See Appendix E, "Binary Information Files", for more information. Syntax -B Extensions .bif For ASCII file describing image. .raw For actual image data. Creator Handmade Software, Inc. Used by Image Alchemy Various image processing software Variations 24 bit true colour, 8 bit gray-scale, and 1 bit black and white. Limitations Paletted files cannot be read in (a work around is to generate a .PAL file and then false colour the gray-scale image using the -F option). Comments BIF files are used to read and write files which consist entirely of image data. You have to generate a text file which describes the format of the data you are trying to read in. This file is called a BIF file. The format of BIF files is documented in Appendix E, Binary Information Files. You then instruct Alchemy to read the image data by giving it the name of the .BIF file. Related options -F False colour Examples Convert the file data to a GIF file: alchemy data.bif -g Copyright (c) 1990-1994 Handmade Software, Inc. 35 Convert the image helen.pcx to a Binary file (this will create two files: helen.raw and helen.bif): alchemy helen.pcx -B 36 Copyright (c) 1990-1994 Handmade Software, Inc. Calcomp CCRF --l Calcomp raster files are used by Calcomp thermal transfer and electrostatic printers. Syntax --l type (lower case l) Parameter type: Thermal Transfer Printer: 0:Uncompressed 1:White Space Suppression 2:Run Length Compression Electrostatic plotter (CCRF): 6:8 bit bytes, 8 bit compression units 7:8 bit bytes, 16 bit compression units 8:8 bit bytes, 32 bit compression units The default is Thermal transfer, uncompressed. Extensions .crf .ccrf .prn Creator Calcomp Used by Calcomp thermal printers and Electrostatic plotters. Variations Black and white or 1-bit CMYK. Comments If there is only black and white data in the image, a 1 bit file will be generated. For colour images, the black plane will be omitted if it is empty. See Appendix G for information on how undercolour removal files control the black content of an image. Since the Calcomp CCRF format is a 1-bit CMYK format you may want to use an undercolour removal file when converting a colour image to this format. See the -C option in Chapter 8 for more information. Related options -C Undercolour removal -_ Offset image Example Convert the Targa file image1.tga to a CCRF file using 16 bit compression units: alchemy page1.tif --l7 Copyright (c) 1990-1994 Handmade Software, Inc. 37 CALS --c Computer-aided Acquisition and Logistics Support (CALS) files are black and white images used by the US Government as part of their transition to electronic media. Syntax --c Extension .cal Creator Defense Logistics Agency (DLA) Used by Department of Defense (DoD) Variations Reads and writes type 1 (Group 4 raster) CALS images. Limitations Document labels, such as document ID and figure ID, are ignored. Comments Since CALS files are always black and white, Alchemy assumes the use of the -b, -8, and -c2 options when writing CALS files. CALS images are Fax Group IV compressed and are therefore a good way of storing black and white line drawings and scans. Example Convert the TIFF file page1.tif to a CALS file: alchemy page1.tif --c 38 Copyright (c) 1990-1994 Handmade Software, Inc. Core IDC --B Core IDC files are used by Core Software's GIS software. Syntax --B Extension .idc Creator Core Software Technology Used by Core Software Technology Variations Reads and writes 1 and 3 band files. Reads and writes 8 bit files. Limitations Only 8 bit images can be read. Alchemy cannot read 2 channel or 4 or more channel images without using the -Z option (see the comments section below for more information). Comments 1 band files are read in as gray-scale images. 3 band files are read in as true colour images. The default colour mapping between RGB and bands 1, 2, and 3 is Red=Band 1, Green=Band 2, and Blue=Band 3, this can be changed by using the -Z option. See the example section below for details. Using the -Z option it is possible to select a single channel or 3 channels when reading a multi- channel Core IDC image. To use the -Z option follow it with a single number to indicate which channel is to be read as a grey-scale image or three numbers to indicate which channels are to be read as a 24 bit colour image. See the example section below for details. Examples Convert the Core IDC file atlanta.idc to a Sun raster file: alchemy atlanta.idc -s Convert the file satellite.image to a Core IDC file. alchemy satellite.image satellite.idc --B Copyright (c) 1990-1994 Handmade Software, Inc. 39 The Core IDC file newyork.idc contains 9 bands,the next examples show various ways to read selected bands out of the image. Convert the first band in the image to a grayscale Sun Raster file. alchemy newyork.idc -Z 1 -s Convert the sixth band in the image to a grayscale Sun Raster file. alchemy newyork.idc -Z 6 -s Convert the image to a 24 bit, colour Sun Raster file, using band 2 as the red channel, band 7 as the green channel, and band 4 as the blue channel. alchemy newyork.idc -Z 2 7 4 -s 40 Copyright (c) 1990-1994 Handmade Software, Inc. Cubicomp PictureMaker --P Cubicomp PictureMaker files are used in broadcast- quality three dimensional modeling and animation. Syntax --P type Parameter type: 0:Allow any size image 1:Adjust image size to 512 x 488 The default is 0. Extension .r8 Red channel image data .g8 Green channel image data .b8 Blue channel image data .a8 Alpha channel image data [optional] Creator Cubicomp Corp. Used by Cubicomp PictureMaker Variations Reads and writes 24 bit true colour images. Limitations If an alpha channel exists, it will be ignored. 8-bit paletted PictureMaker files are unsupported. Comments This format is not the same as IBM Picture Maker. The option for adjusting the image size to 512 x 488 is useful because Cubicomp PictureMaker does not work with images which are not of this exact size. If either the X or Y dimension is larger than 512 or 488, respectively, that dimension will be truncated. If either dimension is smaller than 512 or 488, the image will be padded on the right- hand side or bottom, as necessary, with black. PictureMaker images have either three or four separate files per image: a red file, a green file, a blue file, and an optional alpha channel file. When reading or writing a PictureMaker file specify the name of the .r8 file, Alchemy automatically generates the name of the .g8 and .b8 files When writing a PictureMaker file Alchemy will overwrite, without warning, existing .g8 and .b8 files. Copyright (c) 1990-1994 Handmade Software, Inc. 41 Example Convert the 24-bit JPEG image stones.jpg to PictureMaker files: alchemy stones.jpg --P 42 Copyright (c) 1990-1994 Handmade Software, Inc. Dr. Halo CUT --C Dr. Halo CUT files are used by various MS-DOS based paint programs. Syntax --C Extension .pal Palette and header data .cut Pixel data Creator Media Cybernetics Used by Dr. HALO III Paint Package HALO Desktop Imager Variations 8 bits per pixel Comments Dr. Halo CUT images are actually two files. You specify the name of the .cut file and Alchemy automatically generates the name of the .pal file. When writing a Dr. Halo CUT file Alchemy will overwrite, without warning, existing .pal files. Examples Convert the image test.pcx to a Dr. Halo CUT file: alchemy test.pcx --C Copyright (c) 1990-1994 Handmade Software, Inc. 43 Encapsulated PostScript (EPS) -e EPS files are a subset of PostScript; they may be included by other PostScript files without requiring that the importing software be able to interpret the file. Syntax -e type Parameter type: 0:No preview, Unix newlines 1:Device independent preview, Unix newlines 2:TIFF preview, Unix newlines 10:No preview, Mac newlines 11:Device independent preview, Mac newlines 12:TIFF preview, Mac newlines 20:No preview, MSDOS newlines 21:Device independent preview, MSDOS newlines 22:TIFF preview, MSDOS newlines 100:No preview, Unix newlines, no showpage 101:Device independent preview, Unix newlines, no showpage 102:TIFF preview, Unix newlines, no showpage 110:No preview, Mac newlines, no showpage 111:Device independent preview, Mac newlines, no showpage 112:TIFF preview, Mac newlines, no showpage 120:No preview, MSDOS newlines, no showpage 121:Device independent preview, MSDOS newlines, no showpage 122:TIFF preview, MSDOS newlines, no showpage The default is device independent preview with Unix newlines and showpage (type 1). Extensions .epsi .eps .epi Creator Adobe Systems, Inc. Used by PostScript printers Variations Black and White, Gray-scale, and RGB. Limitations Image Alchemy can only write, not read, EPS images; if you are interested in upgrading to Image Alchemy PS, which can read EPS and PostScript images, please contact us. 44 Copyright (c) 1990-1994 Handmade Software, Inc. Comments If the output is black and white or gray-scale, it will work with any PostScript device. If it's colour, then the CMYK extensions or a level 2 device is required. EPS files are normally written using the UNIX newline convention. To write an EPS file with Macintosh newlines, add 10 to the preview type. To write an EPS file with MS-DOS newlines add 20 to the preview type. See below for an example. To omit the showpage from the end of the EPS file add 100 to the preview type. Some software which imports EPS files does not correctly handle EPS files which contain the showpage. If you are writing an EPS file which you intend to send directly to an EPS output device, such as a printer, you will want to write a type 0 EPS file (No Preview, Unix Newlines, and include the showpage). Related options -_ Offset image Examples Convert the file input.gif to a colour EPS file called input.eps with no preview: alchemy input.gif -e0 -24 Convert the file input.gif to a gray-scale EPS file called gray.eps, with a device independent preview: alchemy input.gif gray.eps -e -b Convert the file test.gif to a black and white EPS file called test.eps, with a no preview and MS-DOS newlines: alchemy test.gif gray.eps -e20 -b -c2 Copyright (c) 1990-1994 Handmade Software, Inc. 45 ER Mapper Raster --m ER Mapper files are used by ER Mapper satellite image analysis software. Syntax --m Extensions .ers Header data . Pixel data Creator Earth Resource Mapping Used by ER Mapper Variations Reads and writes single channel and 3 channel images. Limitations Alchemy cannot read 2 channel or 4 or more channel images without using the -Z option (see the comments section below for more information). Comments ER Mapper files are actually two files, one with the extension .ers and the other without any extension. The .ers file contains header information and the non-extensioned file contains the actual image data. You specify the name of the .ers file and Alchemy automatically generates the name of the other file. When writing an ER Mapper file Alchemy will overwrite, without warning, existing ER Mapper image data files. Using the -Z option it is possible to select a single channel or 3 channels when reading a multi- channel ER Mapper image. To use the -Z option follow it with a single number to indicate which channel is to be read as a grey-scale image or three numbers to indicate which channels are to be read as a 24 bit colour image. See the example section below for details. Examples Convert the Sun Raster file earth.ras to an ER Mapper file: alchemy earth.ras --m The ER Mapper file Landsat_TM_year_1991.ers contains 7 bands; the next examples show various ways to read selected bands out of the image. 46 Copyright (c) 1990-1994 Handmade Software, Inc. Convert the first band in the image to a grayscale Sun Raster file. alchemy Landsat_TM_year_1991.ers -Z 1 -s Convert the fifth band in the image to a grayscale Sun Raster file. alchemy Landsat_TM_year_1991.ers -Z 5 -s Convert the image to a 24 bit, colour Sun Raster file, using band 2 as the red channel, band 7 as the green channel, and band 3 as the blue channel. alchemy Landsat_TM_year_1991.ers -Z 2 7 3 -s Copyright (c) 1990-1994 Handmade Software, Inc. 47 Erdas LAN/GIS --e Erdas files are used by Erdas image processing software. Syntax --e Extensions .lan .gis Creator Erdas Inc. Used by Erdas remote sensing software. Variations Reads and writes 1 and 3 band files. Reads 4, 8, and 16 bit files. Writes 8 bit files. Limitations When writing Erdas files Alchemy does not change the extension depending on the number of bands in the image; according to the specification gray- scale files should have the extension .gis and true colour files should have the extension .lan. Alchemy always uses .lan. Alchemy cannot read 2 channel or 4 or more channel images without using the -Z option (see the comments section below for more information). Comments 1 band files are read in as gray-scale images. 3 band files are read in as true colour images. The default colour mapping between RGB and bands 1, 2, and 3 is Red=Band 1, Green=Band 2, and Blue=Band 3; this can be changed by using the -Z option. See the example section below for details. Using the -Z option it is possible to select a single channel or 3 channels when reading a multi- channel Erdas image. To use the -Z option follow it with a single number to indicate which channel is to be read as a grey-scale image or three numbers to indicate which channels are to be read as a 24 bit colour image. See the example section below for details. Examples Convert the GIS file texas.gis to a Sun raster file: alchemy texas.gis -s 48 Copyright (c) 1990-1994 Handmade Software, Inc. Convert the file satellite.image to a GIS file. alchemy satellite.image satellite.gis -b --e The Erdas file miami.gis contains 4 bands; the next examples show various ways to read selected bands out of the image. Convert the first band in the image to a grayscale Sun Raster file. alchemy miami.gis -Z 1 -s Convert the fourth band in the image to a grayscale Sun Raster file. alchemy miami.gis -Z 4 -s Convert the image to a 24 bit, colour Sun Raster file, using band 2 as the red channel, band 1 as the green channel, and band 4 as the blue channel. alchemy miami.gis -Z 2 1 4 -s Copyright (c) 1990-1994 Handmade Software, Inc. 49 First Publisher ART --F First Publisher ART files are black and white images used as clip art by First Publisher. Syntax --F Extension .art Creator Software Publishing Corp. Used by First Publisher Variations Black and white, 1 bit per pixel. Comments Since ART files are always black and white, 1 bit per pixel, Alchemy assumes use of the -c2 and -b options when writing them. Examples Convert the image scan.pcx to a First Publisher ART file: alchemy scan.pcx --F 50 Copyright (c) 1990-1994 Handmade Software, Inc. Freedom of Press --f Freedom of Press is a PostScript interpreter from Custom Applications that converts PostScript files to raster files. The Freedom of Press format is one of the file types it can create. Syntax --f Extension .fop Creator Custom Applications Limitations Output only. Only CMYK 1 bit per component per pixel supported. Comments Freedom of Press images are actually two files, a data file and an info file. You specify the name of the data file and Alchemy automatically generates the name of the info file. The output file is normally output.001, output.002, etc. Alchemy will strip the first part of the name and replace it with 'info', so if you specified an output filename of output.005 there will be another file created called info.005. If you don't specify an extension, Alchemy will use .fop, so you'll get two files named filename.fop and info.fop. Alchemy will overwrite info files without warning. Since Freedom of Press images are 1-bit CMYK you may want to use an undercolour removal file when converting a colour image to this format. See the -C option in Chapter 7 for more information. Related options -C Undercolour removal Example Convert the file image.tga to a Freedom of Press image called output.003 and info.003, controlling the undercolour removal process using sample.ucr, scaling the image to 2500 pixels across (and scaling proportionately vertically) using nearest neighbor scaling, and conserving memory: alchemy --f -Csample.ucr -X2500 -+ -$ image.tga output.003 Copyright (c) 1990-1994 Handmade Software, Inc. 51 GEM VDI Image File --g VDI files are files that were developed by Digital Research for use with GEM. Syntax --g Extension .img Creator Digital Research Inc. Used by GEM Variations Reads 1-8 bit grayscale and 3 and 4 bit colour files. Writes 1, 3, and 4 bit grayscale and 3 and 4 bit colour files. Limitations The support for colour and multiple bit grayscale GEM files is not very universal. Therefore make sure the application you are using to read the GEM files supports them. Alchemy defaults to writing out a 1 bit, black and white GEM file. You can explicitly force a 3 plane colour file by use of the -c8 option and a 4 plane colour file by use of the -c16 option (you may add a -b to write a grayscale file instead of a colour file). Comments Because colour GEM files have only 3 or 4 bits of information and no palette support the quality is generally not very good for scanned images. The GEM format seems to have been designed for line drawings. Examples Convert the image scan.pcx to a black and white GEM file: alchemy scan.pcx --g Convert the image bigscan.tga to a 640x480, 8 colour GEM file, using nearest neighbor scaling and type 2 dithering: alchemy bigscan.tga -c 8 --g -X640 -Y480 -d2 52 Copyright (c) 1990-1994 Handmade Software, Inc. Do the same thing but write an 8 shade grayscale file with no dithering: alchemy bigscan.tga -c 8 --g -X640 -Y480 -d -b Copyright (c) 1990-1994 Handmade Software, Inc. 53 GIF -g GIF files were developed by CompuServe as a machine independent image file format. GIF files are the most popular way of storing 8 bit, scanned or digitized images. In addition the compression ratio achieved by GIF files is usually better than any other 8 bit format in common use. Syntax -g version Parameter version: 0:GIF87A 1:GIF89A The default is GIF87A. Extension .gif Creator CompuServe, Incorporated Used by CompuServe Everyone Variations Reads 1 through 8 bit GIF87A and GIF89A interleaved and non-interleaved files. Writes 1 through 8 bit GIF87A and GIF89A non- interleaved files. Limitations When reading GIF89A files only the first image in the file is read. Any text, overlays, pauses, palette changes, etc. are ignored. Because GIF files only store the size of the palette to the nearest power of 2 the exact palette size is lost when converting to and from GIF files. For example, if you convert a 240 colour Sun Raster file to a GIF file and back to a Sun Raster file the resulting Sun Raster file will have 256 colours. Comments GIF89A files are a new variation of GIF files that was introduced in 1990 which allow the inclusion of text and simple animations in GIF files. When writing a file you probably want to use the GIF87A variation, since the GIF89A extensions aren't necessary to store single images and a lot of other software still can't read GIF89A images. The only advantage to GIF89A is that aspect ratio information is preserved (GIF87A does not have a provision for storing aspect ratio). 54 Copyright (c) 1990-1994 Handmade Software, Inc. The GIF format includes a field for storing the colour to be used for the background when viewing files. Alchemy does not make use of this value. Alchemy sets the background colour to the darkest colour in the palette when viewing files and organizes the palette such that the first colour is the darkest colour when writing GIF files, if the palette is created by Alchemy (you can override this by using the -z option). Related options -z Palette Selection Examples Convert the image test.pcx to a GIF87A image. alchemy test.pcx -g Convert the file input.tga to a 16 colour GIF89A file: alchemy input.tga -c16 -g1 Copyright (c) 1990-1994 Handmade Software, Inc. 55 GOES --G GOES files are used for satellite image data. Syntax --G goesType Parameter goesType: 0:GARS format 1:McIDAS format The default is 0 (GARS format). Extension .goe Creators The University of Wisconsin National Oceanic and Atmospheric Administration (NOAA) National Environmental Satellite Data Information Service (NESDIS) Used by Various satellite image processing software, including the McIDAS system. Variations Reads 8, 16, and 32 bits per pixel GOES images. Writes 8 bits per pixel images. Limitations When reading 16 and 32 bit images Alchemy discards all but the top 8 bits of data. Alchemy discards any calibration data and level maps when reading images. Because of difficulty in getting a sufficient number of test images in the GOES format (especially the PUT format) reading GOES images has not been thoroughly tested. If you have any GOES images which Alchemy does not read correctly please contact us. Comments The GARS format is a 7680 bytes per block, Motorola byte-order, EBCDIC format; the MCIDAS format is a continuous data, Intel byte-order, ASCII format. Since GOES images are always grayscale, Alchemy assumes the use of the -b and -8 options when writing a GOES file. 56 Copyright (c) 1990-1994 Handmade Software, Inc. GOES images contain a lot of information which is not part of the image data. This information includes the time and date the image was captured, the satellite which captured the image, the type of instrumentation used, etc. When reading a GOES image this information is discarded; when writing a GOES image 0 is written for all values for which data is unavailable. Examples Convert the Erdas file, florida.gis, into a GOES GARS image: alchemy florida.gis --G0 Do the same thing, but write out a GOES McIDAS image: alchemy florida.gis --G1 Copyright (c) 1990-1994 Handmade Software, Inc. 57 Hitachi Raster Format --h Hitachi Raster Format (HRF) files are black and white images used by CADCore. Syntax --h Extension .hrf Creator Hitachi Software Engineering Co., Ltd. Used by Information and Graphics Systems, Inc. (IGS) Comments Since HRF files are always black and white, Alchemy assumes the use of the -b, -8, and -c2 options when writing HRF files. Example Convert the TIFF file page1.tif to a HRF file: alchemy page1.tif --h 58 Copyright (c) 1990-1994 Handmade Software, Inc. HP Printer Command Language (PCL) -P HP PCL files are used by HP LaserJets and compatible printers. Syntax -P type Parameter type: 0:Uncompressed 1:RLE compressed 2:TIFF compressed 3:Delta Row compressed 10:Landscape, Uncompressed 11:Landscape, RLE compressed 12:Landscape, TIFF compressed 13:Landscape, Delta Row compressed 100:LaserJet 4, Uncompressed 101:LaserJet 4, RLE compressed 102:LaserJet 4, TIFF compressed 103:LaserJet 4, Delta Row compressed 110:LaserJet 4, Landscape, Uncompressed 111:LaserJet 4, Landscape, RLE compressed 112:LaserJet 4, Landscape, TIFF compressed 113:LaserJet 4, Landscape, Delta Row compressed The default is type 0. Extension .pcl Creator Hewlett-Packard Company Used by HP LaserJet printers HP compatible laser printers Variations 1 bit per pixel, black and white. Reads and writes uncompressed, RLE compressed, TIFF compressed, and Delta Row Compressed files. Reads and writes portrait and landscape files. Limitations In addition to raster images, PCL files can include text and vector graphics information. When reading Alchemy only pays attention to raster images in the file and attempts to skip everything else. See Appendix A, Answers to Frequently Asked Questions, for a further discussion of this. Copyright (c) 1990-1994 Handmade Software, Inc. 59 The only resolutions allowed in PCL files are 75 DPI, 100 DPI, 150 DPI, and 300 DPI (and, in the case of LaserJet 4 type files, 200 DPI and 600 DPI) and the X and Y resolution are the same. If you specify a non-allowable resolution Alchemy automatically alters the resolution to the next higher resolution. For example, if you specify 250 DPI Alchemy will write a 300 DPI PCL file. If no resolution is specified either on the command line or in the input file Alchemy automatically chooses the smallest resolution which will allow the entire image to fit on an 8.5" x 11" page. Comments Since PCL files are always 1 bit, black and white files, Alchemy assumes the use of the -b, -c2, and -8 options when writing a PCL file. When converting colour or gray-scale images to PCL you will probably want to scale the output so the image will be larger than the input image. This will allow the dithering to preserve more detail in the image. 60 Copyright (c) 1990-1994 Handmade Software, Inc. Not all PCL compatible printers can print all types of compressed PCL file. Specifically, LaserJet II, IID, and earlier printers can print only uncompressed PCL files. LaserJet IIp printers can print only uncompressed and RLE compressed files. LaserJet III, IIID, IIIp, IIIsi, and 4 printers can print all types of compressed PCL files. In general, the higher the compression type, the better the compression ratio. The Landscape option can be used to write a landscape PCL file. Because of changes in the PCL format, only LaserJet III and newer printers will correctly print Alchemy produced landscape PCL files. PCL files can be used to generate output which can be printed on HP LaserJet and compatible printers. The easiest method is to simply generate a .PCL file and then copy it to the printer by using the copy command (when using the copy command from MS- DOS you will have to use a /B to make sure the entire file is copied to the printer; see the example below for more information). For MS-DOS users it is possible to write a PCL file directly to a HP LaserJet or compatible printer. If you use the name of the device as the output file name Alchemy will redirect output to that device (for example, use prn: as the output file name if your LaserJet is attached to the prn: port) . You may want to adjust the output gamma to compensate for dot gain when generating a PCL file to print on a laser printer. See Appendix A, Answers to Frequently Asked Questions, for more information on dot gain. The best results are usually achieved with dithering type 3, a serpentine raster, and some dithering noise (use -ds3 10, for example). Related options -_ Offset image Examples Convert the image image.gif to a HP PCL file, using no compression: alchemy image.gif -P Copyright (c) 1990-1994 Handmade Software, Inc. 61 Convert the image small.gif to a HP PCL file called out.pcl with dimensions of 2000 by 2000 at 300 DPI, performing gamma correction to compensate for dot gain, and using dithering type 3, with a serpentine raster, and adding dithering noise : alchemy small.gif out -P -X2000 -Y2000 -D 300 300 -Gi 1.0 -Go 2.0 -ds3 10 Convert the image small.gif to a HP PCL file called out2.pcl with dimensions of 2000 by 2000 at 300 DPI, using TIFF compression: alchemy small.gif -P2 -X2000 -Y2000 -D 300 300 out2 Print the image madonna.gif directly to your LaserJet 4 at the largest resolution, using Delta Row compression with dithering type 22 (printing directly to the printer works only in the MS-DOS version of Alchemy): alchemy madonna.gif prn: -P104 -D600 600 - Xb4800 -YB6600 -+ -d22 Print all the TIFF files in the current directory directly to a LaserJet, while scaling them to fill the page: alchemy *.tif prn: -P -D 300 300 -Xb2400 - Yb3000 -+ 62 Copyright (c) 1990-1994 Handmade Software, Inc. HP Raster Transfer Language (RTL) --r RTL files are used by HP colour raster printers and plotters. Syntax --r type Parameter type: 0:PaintJet, PaintJet 300XL, PaintJet 1200C uncompressed 1:650C and HP7600 uncompressed 2:650C and HP7600 TIFF compressed 3:HP7600 planar, uncompressed 4:HP7600 planar, TIFF compressed 5:HP7600 planar, Group III compressed 6:DesignJet 600 and 650C on-the-fly, uncompressed 7:DesignJet 600 and 650C on-the-fly, TIFF compressed 9:PaintJet 300XL and PaintJet 1200C TIFF compressed 10:NovaJet TIFF compressed The default is Type 2. Extension .rtl Creator Hewlett-Packard Company Used by HP raster plotters and printers including PaintJets, DesignJets, and HP 7600 Series plotters. NovaJet Plotters. Variations CMYK, 1 bit per component per pixel. Black and white, 1 bit per pixel. Limitations Output only. Comments RTL files can be used to produce output which can be printed on HP colour printers and raster plotters. The file can be printed by sending the file to the plotter. Compression types 6 and 7 are equivalent to types 1 and 2 except they tell the plotter it may plot the data as received instead of waiting for the entire image. This is useful on the DesignJet plotters which have small buffers compared to the imageable area. Copyright (c) 1990-1994 Handmade Software, Inc. 63 The NovaJet option causes Alchemy to create RTL files which are compatible with NovaJet plotters. Alchemy will generate a colour RTL file unless the input file is black and white or grayscale or the -b option is specified as part of the conversion. There is no additional setup required for the PaintJet or DesignJet plotters. HP7600 series plotters should be in HP-GL/2 mode; best results will generally be achieved with compensation off. To get colour plots from the HP7600 series the plotter must be in 4 or 5 pass mode. If the input is black and white, you can do the conversion without an undercolour removal file and with dithering off. This will result in a faster conversion. If the input is gray-scale, you probably do want to use an undercolour removal file to perform density correction, but with 100% black removal (the black removal tables should contain 0 through 255, increasing by one each line) so that the output won't contain cyan, magenta, or yellow. The sample directory on the distribution diskette has a UCR file called gray.ucr which has 100% black removal. MS-DOS users can send the RTL file directly to the plotter when generating an RTL file of type 0, 1, 2, 6, 7, 9, or 10. To send the file directly give the name of the output device as the output file (for example, if your plotter is connected to your computer via lpt1: specifying lpt1: as the output file will send output directly to that device). Since the HP RTL format is a 1-bit CMYK format you may want to use an undercolour removal file when converting a colour image to this format. See the -C option in Chapter 8 for more information. Related options -C Undercolour removal -d Specify dither type -_ Offset image 64 Copyright (c) 1990-1994 Handmade Software, Inc. Examples Convert the black and white image test.wpg to a RTL file for a PaintJet called test.rtl, not using a UCR file and with dithering off: alchemy test.wpg --r0 -d0 Convert the file image.tga to a RTL file for a PaintJet called image.rtl, using the undercolour removal file sample.ucr: alchemy image.tga --r0 -Csample.ucr Convert the file image.tga to a planar RTL file called image.rtl using TIFF compression, controlling the undercolour removal process using sample.ucr, scaling the image to 3000 pixels across using good quality scaling, preserving the aspect ratio (by proportionately scaling the image vertically), and conserving memory: alchemy image.tga --r4 -Csample.ucr -Xb3000 -+ -$ Convert the file image.tga to an RTL file for a DesignJet 650C, sending the image directly to the plotter, using the UCR file sample.ucr, dithering type 3 (with a serpentine raster), and scaling the image to be 17 inches wide and preserving the aspect ratio (the plotter is attached to the lpt1: port of an IBM PC): alchemy image.tga lpt1: --r7 -Csample.ucr -ds3 -Xb17i -+ Copyright (c) 1990-1994 Handmade Software, Inc. 65 HP-48sx Graphic Object (GROB) --H Graphic Object files are used by HP-48sx calculators. Syntax --H type Parameter type: 0:Binary 1:ASCII The default is Binary. Extension .grb .asc Creator Hewlett-Packard Company Used by HP-48sx calculators. Variations Black and white, 1 bit per pixel. Comments Since GROB files are always black and white, Alchemy assumes the use of the -b, -8, and -c2 options when writing GROB files. Example Convert the image madonna.gif to a ASCII HP-48sx GROB file alchemy madonna.gif --H 1 66 Copyright (c) 1990-1994 Handmade Software, Inc. HSI JPEG --j The HSI JPEG format is a variation of the JPEG format that was designed by Handmade Software to better compress paletted images. Syntax --j Extension .jpg Creator Handmade Software, Inc. Used by Image Alchemy GIF2JPG (another Handmade Software product) Variations 8 bit paletted Comments Paletted images often have large areas where the image consists of 1 or 2 colours; JPEG compression does a poor job on these sections when compared to LZW compression. HSI JPEG files are a combination of JPEG and LZW compression. HSI JPEG files are not compatible with JPEG or JFIF files. If you intend to transfer files to other systems do not use this format, use the standard JPEG format instead (using the -j option). If you are interested in adding support for HSI JPEG files to your software please contact us for information on the format. Example Convert the file madonna.gif to an HSI JPEG file: alchemy madonna.gif --j Copyright (c) 1990-1994 Handmade Software, Inc. 67 HSI Palette -l PAL files are palettes which are ASCII files that can be edited with a text editor. Syntax -l (lower case L) Extension .pal Creator Handmade Software, Inc. Used by Image Alchemy Variations Palette files are always ASCII files. Limitations .PAL files contain only a palette. Comments The format of PAL files is described in Appendix H. Related options -f Match image to specified palette -F False colour with specified palette -L Output Multi-Image Palette Examples Extract the palette from the GIF file madonna.gif: alchemy madonna.gif -l Convert the file image.tga to a GIF file, matching the palette found in standard.pal: alchemy image.tga -g -f standard.pal 68 Copyright (c) 1990-1994 Handmade Software, Inc. HSI Raw -r HSI Raw files are used internally by Image Alchemy when converting between certain combinations of image formats. If you are interested in converting custom format images to be used with Image Alchemy we suggest using HSI Raw Files. Syntax -r Extension .raw Creator Handmade Software Inc. Used by Image Alchemy Variations 8 bit paletted and 24 bit true colour, uncompressed, not packed. Comments This format is used internally as temporary files by Alchemy when doing certain image conversions; it can also be explicitly read and written. This format is described in Appendix F. Examples Convert the file test.lbm to a raw file: alchemy test.lbm -r Copyright (c) 1990-1994 Handmade Software, Inc. 69 IBM Picture Maker --i IBM Picture Maker files are used by IBM presentation software. Syntax --i Extension .pic Creator IBM Corp. Used by IBM Storyboard Live! Variations Reads and writes 256 colour Picture Maker files. Limitations 16 colour Picture Maker files are not supported. Picture Maker images cannot be larger than 640x480. Comments This is not the same format as Cubicomp PictureMaker. Picture Maker files may be either 320x200 or 640x480. Image Alchemy will write the smallest variation that the image will fit in, with the image centered and the borders filled with colour 0. If you attempt to write a Picture Maker file which is larger than 640x480 an error is generated. Example Convert the PCX file, giraffe.pcx, into an IBM Picture Maker file: alchemy giraffe.pcx --i 70 Copyright (c) 1990-1994 Handmade Software, Inc. IFF/ILBM -i IFF (Interchange File Format) files are used by Amiga computers for storing a number of types of data, including images, text, and music; ILBM (InterLeaved BitMap) is a type of IFF file used to store images. Syntax -i Extensions .lbm .iff .ilbm Creator Commodore-Amiga Corp. Used by Amiga Deluxe Paint Variations Reads 1 through 8 bit, 24 bit, HAM, and PBM images Writes 1 through 8 bit and 24 bit images. Limitations Dynamic Hi-Res images are not supported. Does not write images in any of the Amiga-specific display modes. Comments If you're writing an ILBM file for use on an Amiga, you probably want to write either a paletted file with 32 colours or a 24 bit file. 24 bit ILBM files can then be converted to one of the Amiga-specific display modes with various third-party utilities. Example Convert the file input.pcx to an IFF/ILBM file called output.lbm with 32 colours: alchemy input.pcx output.lbm -i -c32 Copyright (c) 1990-1994 Handmade Software, Inc. 71 Img Software Set --Q The Img Software Set is a collection of tools for manipulating graphic images freely available for various UNIX workstations. Syntax --Q Extensions .img .p .a Creator Paul Raveling Used by Img Software Set Variations Reads and writes 8 bit paletted and 24 bit images. Limitations Alchemy does not read nor write compressed (.Z) images. Use the UNIX supplied uncompress program to decompress those images before reading with Alchemy. Comments The Img Software Set is available via anonymous ftp as expo.lcs.mit.edu:contrib/img_1.3.tar.Z or venera.isi.edu:pub/img_1.3.tar.Z or on floppy disk from us. Example Convert the Sun Raster file test.ras to an Img Software Set file: alchemy test.ras --Q 72 Copyright (c) 1990-1994 Handmade Software, Inc. Jovian VI --J Jovian VI files are created by the Jovian Logic video capture boards. Syntax --J Extensions .vi Creator Jovian Logic Corp. Used by Jovian Logic Variations Reads 1, 4, 6, and 8 bit gray-scale images, 4 and 8 bit paletted images, and 16 and 24 bit true colour images. Writes 8 bit gray-scale, 4 and 8 bit paletted images, and 16 and 24 bit true colour images. Limitations Reads files with 6 and 8 bit palettes, always writes 6 bit palettes. Gray-scale files are always 8 bit. Comments When writing a VI file the palette always starts at 0, but colour 0 will not necessarily be black (this is the way that Jovian VI files are written). Example Convert the GIF file, test.gif, to a 16 colour VI file: alchemy test.gif --J -c16 Copyright (c) 1990-1994 Handmade Software, Inc. 73 JPEG/JFIF -j JPEG is an image file format that uses a lossy compression technique to achieve high compression ratios. See Appendix C, JPEG Compression, for more information on the JPEG file format. Syntax -j[coding] quality Parameters coding: Specify the type of entropy coding to perform. none:default Huffman coding h:optimum Huffman coding quality: 1 through 100 (larger is higher quality) The default quality is 32. Extension .jpg Creator Joint Photographic Experts Group (JPEG) Used by Lossy compression of photographic images. Variations Gray-scale images are saved as single channel JPEG files; colour images are saved as three channel JPEG files. Reads and writes baseline JPEG with CCIR-601 YCbCr colour space, interleaved components, Huffman coded. Alchemy can read files with any component sub- sampling up to 4x4; it always writes 2h:1v 1h:1v 1h:1v. Alchemy JPEG files comply with the industry standard 'JFIF' interchange format. Limitations JPEG files are always lossy, which means that the compressed image is not identical to the original image. At high quality factors (32 and above) this loss is generally so slight as to be barely noticeable. There is no quality factor which is guaranteed to be lossless. 74 Copyright (c) 1990-1994 Handmade Software, Inc. Comments By default, Image Alchemy uses a fixed set of Huffman tables to compress an image. If the -j is immediately followed by an 'h', Alchemy will generate a set of custom tables optimized for the image and quality factor. This usually produces 5-20% better compression (depending on the image content and quality factor) but requires an additional pass over the image data, so it takes a little longer to compress (there's no effect on the decompression time). Quality may vary between 1 and 100; the default is 32. The higher the number the higher the quality of the image and the lower the compression ratio. Quality factors below 10 will produce images with significant loss of quality. JPEG files are based on the Joint Photographic Experts Group (JPEG) CD 10918-1 draft standard. Since JPEG compression was designed for use with continuous tone images (such as those produced by a scanner or digitizer), poor results can be expected when compressing line drawings. Related options -q Apply Smoothing when decompressing a JPEG image. Because JPEG compression works on 8x8 pixel blocks there may be discontinuities at the edges of these blocks producing block artifacts. Smoothing attempts to reduce these artifacts. Smoothing is really only necessary at very low quality settings (less than 10); even then the effects of smoothing are not particularly significant. Examples Convert the file photo.tga to a JPEG file called photo.jpg, using a high quality setting: alchemy photo.tga -j70 Convert the file photo.tga to a JPEG file called photo.jpg, using a low quality setting and generating optimum Huffman tables: alchemy photo.tga -jh10 Convert the JPEG file, lores.jpg, to a PCX file using smoothing: alchemy lores.jpg -p -q Copyright (c) 1990-1994 Handmade Software, Inc. 75 Lumena CEL --L Lumena CEL files are used by Time Arts software. Syntax --L Extension .cel Creator Time Arts Used by Lumena Variations Reads and writes 15 and 32 bit images. Limitations The Alpha channel in 32 bit images is ignored. Example Convert the file test.tga to a Lumena CEL file: alchemy test.tga --L 76 Copyright (c) 1990-1994 Handmade Software, Inc. Macintosh PICT/PICT2 -m PICT files were created by Apple Computer as a common format for Macintosh applications to use. Virtually every Macintosh application can use PICT files. Syntax -m macBinary Parameters macBinary: 0:Do not write a MacBinary file 1:Write a MacBinary file The default is to not write a MacBinary file. Extensions .pict .pic Creator Apple Computer, Inc. Used by Macintosh computers Variations Reads 1, 2, 4, 8, 16, and 32 bit PICT and PICT2 images Writes 1, 2, 4, 8, and 32 bit PICT2 images. Limitations Only pays attention to pixMaps in the image; attempts to skip everything else. Comments Due to the enormous number of options allowed in PICT files, reading PICTs may not always work. See Appendix A, Answers to Frequently Asked Questions, for more information. Adding a MacBinary header to a MacPaint file is useful if transferring the file to a Macintosh computer by modem. The MacBinary header will allow the Macintosh to automatically recognize the file as a MacPaint file. Example Convert the file input1.gif to a Mac PICT file called input1.pic: alchemy input1.gif -m Copyright (c) 1990-1994 Handmade Software, Inc. 77 MacPaint --t MacPaint files are black and white images used by Macintosh computers. Syntax --t macBinary Parameters macBinary: 0:Do not write a MacBinary file 1:Write a MacBinary file The default is to not write a MacBinary file. Extensions .mac Creator Apple Computer, Inc. Used by Macintosh computers Variations 1 bit per pixel, black and white. Limitations MacPaint images are always 576x720 pixels. If you attempt to write a MacPaint image which is larger, Alchemy will report this as an error. If you write an image which is smaller Alchemy will pad the image with white space along the right-hand side and bottom. Because MacPaint images are always black and white, the -c2, -8, and -b options are assumed when writing an image. Comments Adding a MacBinary header to a MacPaint file is useful if transferring the file to a Macintosh computer by modem. The MacBinary header will allow the Macintosh to automatically recognize the file as a MacPaint file. Example Convert the file input1.gif to a MacPaint file called input1.mac: alchemy input1.gif --t 78 Copyright (c) 1990-1994 Handmade Software, Inc. MTV Ray Tracer --M MTV files are used by the MTV RayTracer, a public domain ray tracer for Suns and other workstations. Syntax --M Extension .mtv Creator Mark T. VandeWettering Used by MTV Raytracer Variations 24 bit true colour. Comments MTV is a public domain ray-tracer available free of charge via anonymous ftp from drizzle.cs.uoregon.edu or via floppy disk from us. Example Convert the file spheres.img to a MTV file: alchemy spheres.img --M Copyright (c) 1990-1994 Handmade Software, Inc. 79 Multi-Image Palette -L This option will generate an optimum palette for a number of images. This is useful for finding a common palette where multiple images are used (animations, for instance). Syntax -L filename Parameters filename: name of the output file to contain the optimized palette Extension .pal Creator Handmade Software, Inc. Used by Image Alchemy Variations Palette files are always ASCII files. Limitations .PAL files contain only a palette. Comments The format of PAL files is described in Appendix H. This output option is unique in that it will cause Alchemy to generate only one output file, independent of how many input files are specified (the other output options generate one output file per input file). Also the file name of the output file must be specified immediately after the -L option (ordinarily the output file name can appear anywhere on the command line). Related options -f Match image to specified palette -F False colour with specified palette -l Generate a palette file for a single image Examples Generate an optimum palette called final.pal for all GIF files in the current directory: alchemy -- *.gif -L final.pal Now map all the GIF files to that palette, putting the results in a sub-directory call new (the files cannot be placed in the current directory because the file names would conflict with the original image file names): alchemy -- *.gif -f final.pal new\ 80 Copyright (c) 1990-1994 Handmade Software, Inc. OS/2 Bitmap (BMP) -O OS/2 BMP files are used by IBM OS/2 2.0. Syntax -O compressionType (Uppercase letter o) Parameter compressionType: 0:None 1:RLE The default is none. Extension .bmp Creator IBM Corp. Used by OS/2 2.0 Variations Reads 1, 4, 8, and 24 bit RGB (raw), RLE4, and RLE8 files. Writes 1, 4, 8, and 24 bit RGB (raw), RLE4, and RLE8 files. Examples Convert the image test.jpg to a OS/2 BMP file: alchemy test.jpg -O Copyright (c) 1990-1994 Handmade Software, Inc. 81 PCPAINT/Pictor Page Format -A The Pictor format was designed by John Bridges. It is optimized so that an image can be loaded into various IBM PC graphics adapters very quickly; it does this by almost exactly duplicating the organization of the graphics adapter memory. This makes the format hardware dependent. Syntax -A type Parameter type: 0:320x200x4 CGA* 1:320x200x16 PCjr/Tandy* 2:640x200x2 CGA* 3:640x200x16 EGA 4:640x350x2 EGA 5:640x350x4 EGA 6:640x350x16 EGA 7:720x348x2 Hercules* 8:640x350x16 VGA 9:320x200x16 EGA 10:640x400x2 AT&T/Toshiba* 11:320x200x256 VGA/MCGA 12:640x480x16 VGA 13:720x348x16 Hercules InColor* 14:640x480x2 VGA/MCGA 15:800x600x2 EGA/VGA 16:800x600x16 EGA/VGA 17:640x400x256 SVGA 18:640x480x256 SVGA 19:800x600x256 SVGA 20:1024x768x2 SVGA 21:1024x768x16 SVGA 22:360x480x256 VGA 23:1024x768x256 SVGA The default is 640x480x256 SVGA. *These modes are not yet supported (if you are interested in support for any of these modes please contact us). Extension .pic .clp Creator John Bridges Used by PCPAINT GRASP Variations There are variations for most IBM and third party graphics adapter display modes. 82 Copyright (c) 1990-1994 Handmade Software, Inc. Limitations Only the EGA and VGA modes are supported at this time. Text modes are not supported. Comments Some Pictor files do not contain palettes. For those files Alchemy will default to using a standard palette appropriate to the display mode the file was saved in. However, the image may not use the default palette; in that case you can read the palette from another file with the -F false colour option. Related options -F False colour Example Convert the file image.pcx to a Pictor file called image.pic, for 800x600x256 SVGA mode: alchemy image.pcx -A19 Copyright (c) 1990-1994 Handmade Software, Inc. 83 PCX -p PCX files are used extensively by IBM PC computers. Originally created by ZSoft for use by their paint software, PCX files can be read and written by almost all MS-DOS paint software and desktop publishing software. A variation of PCX file, DCX, is used by many MS- DOS fax boards. Syntax -p type Parameter type: 0:Standard PCX 1:DCX 2:PCJ The default is standard PCX. Extension .pcx.dcx Creator ZSoft Corporation Used by PC Paint Publisher's Paintbrush Most paint and desktop publishing software can read and write PCX files. Fax board software uses the DCX variation of PCX. Variations 1, 4, 8, and 24 bits per pixel for standard PCX files. 1 bit per pixel for DCX files. 8 bits per pixel for PCJ files. Limitations PCX format files are often written out incorrectly; Alchemy attempts to figure out what is wrong and make intelligent decisions (things Alchemy can deal with include PCX files without palettes, files missing the last line of image data, and files with illegal (and incorrect) combinations of bits per pixel and planes). The 24 bit PCX file variation is new and many programs which support PCX do not support the 24 bit variation. Therefore, unless you are sure that the software you are using can read a 24 bit PCX file, you probably want to use the -8 option to force Alchemy to write a paletted file when generating a PCX file. 84 Copyright (c) 1990-1994 Handmade Software, Inc. DCX files are multiple page PCX images which are used by various manufacturers of fax boards and fax software. Alchemy only reads the first page of a DCX file. Alchemy always writes single page DCX files. Comments Because so many software packages can read and write PCX files we are especially interested in supporting as many variations as possible. If you have any PCX files which Alchemy does not read correctly please contact us. Since DCX files are always 1 bit, black and white images, Alchemy assumes the use of -b -c2 -8 when writing the DCX variation of PCX. Recently some of the header information in PCX files has been changed to include image resolution information. Some fax board software makes use of this information when transmitting PCX or DCX files as faxes. See the example section below for an example of how to specify image resolution when writing a PCX file. PCJ files are a variation of 256 colour PCX files which have the palette in a separate file. The palette file has the extension .p13. Alchemy will automatically look for the palette file in the same directory as the PCJ file when reading. Related options -D Specify image resolution. Examples Convert the GIF file, lush.gif, to a PCX file: alchemy lush.gif -p Convert the scanned image, page1.tif, to a DCX file: alchemy page1.tif -p1 Convert the scanned image, page2.tif, to a DCX file, specifying an image resolution of 200x100 (a common resolution for fax images): alchemy page2.tif -p1 -D 200 100 Convert the image, flower.tif, to a PCJ file: alchemy flower.tif -p2 Copyright (c) 1990-1994 Handmade Software, Inc. 85 PDS --p PDS labeled images are used by NASA for planetary images. Syntax --p Extensions .ibg .imq Creator NASA Used by NASA distributes collections of planetary images on CD-ROM in PDS format. Variations Reads 1 and 8 bit uncompressed and 8 bit first difference Huffman compressed files. Writes 8 bit gray-scale uncompressed PDS files. Limitations PDS images must begin with either an "SFDU_LABEL" or a "FILE_TYPE" record for Alchemy to be able to identify it. Occasionally a PDS labeled image has a palette. There doesn't seem to be any standard format for the palette; Image Alchemy handles the palettes we've encountered. Any portions of the PDS labels not required to extract the image, such as longitude and latitude, are ignored. Comments Since Image Alchemy only writes gray-scale PDS images, Alchemy assumes the use of the -b option when writing PDS files. Some PDS images actually consist of two files, a label file and a data file. To read that type image you should use the name of the label file and Alchemy will find the data file. Example Convert the GOES file, phoenix.goe, into a PDS labeled image: alchemy phoenix.goe --p 86 Copyright (c) 1990-1994 Handmade Software, Inc. Portable BitMap (PBM) -k The Portable BitMap format was developed by Jef Poskanzer to allow the transferring of black and white image files between different workstations. The PBM format has grown to include black and white, gray-scale, and true colour images, a large set of programs to convert various other image formats to and from PBM, and a set of image manipulation tools. Syntax -k Extensions .pnm .pbm .pgm .ppm Creator Jef Poskanzer Used by Portable BitMap Package Various workstation graphic programs Variations Reads and writes 1, 8, and 24 bit RAWBITS (binary) images. To write out a PBM file use -b -c2. To write out a PGM file use -b -c256. To write out a PPM file use -24. Limitations When writing a PBM file Alchemy always uses the .pnm extension (the extension should be changed based on the type of file being written). Comments By convention the extension of a PBM file changes depending on the type of image data which it is storing, based on the following table: .pnm Portable aNyMap (Any of those below) .pbm Portable BitMap (Black and white) .pgm Portable GrayMap (Gray-scale) .ppm Portable PixelMap (True colour) Alchemy does not make use of this convention when writing images, always writing files with the extension .pnm. The PBM package is a set of image manipulation tools which run on various workstations. The software is available free of charge via anonymous ftp from expo.lcs.mit.edu as contrib/pbmplus.tar.Z, ftp.ee.lbl.gov as pbmplus.tar.Z, or via floppy disk from us. Copyright (c) 1990-1994 Handmade Software, Inc. 87 Examples Convert the file sun.im32 to a PBM file: alchemy sun.im32 -k -b -c2 Convert the file sun.im32 to a PGM file, overwriting any existing sun.pnm file: alchemy sun.im32 -k -b -c256 -o Convert the file sun.im32 to a PPM file called image77: alchemy sun.im32 image77 -k -24 -. 88 Copyright (c) 1990-1994 Handmade Software, Inc. Puzzle --U The Puzzle format is used by the UNIX supplied Puzzle program Syntax --U Extensions .pzl .puzzle .cm Creator Unknown Used by The puzzle program. Variations 8 bits per pixel Comments Since puzzle files are always paletted, Alchemy assumes the use of the -8 option when writing a puzzle file. Example Convert the file einstein.im8 to a Puzzle file: alchemy einstein.im8 --U Copyright (c) 1990-1994 Handmade Software, Inc. 89 Q0 --q The Q0 format is apparently commonly used by various Japanese scanning, painting, and viewing software to store 24 bit images. Handmade Software has no information other than a basic description of the format and some sample images; if you have further information on the Q0 format please contact us. Syntax --q Extensions .q0 For pixel data .rgb For pixel data .fal For image header information Creator Unknown Used by Various Japanese image processing software. Variations 24 bits per pixel Comments Q0 files are actually two files, one with the extension .rgb or .q0 and the other with the extension .fal. The .rgb or .q0 file contains the actual image data and the .fal file contains the header information. You specify the name of the .rgb or .q0 file and Alchemy automatically generates the name of the .fal file. When writing a Q0 file Alchemy will overwrite, without warning, existing .fal files. Since Q0 files are always true colour, Alchemy assumes the use of the -24 option when writing a Q0 file. Example Convert the file dogcow.gif to a Q0 file: alchemy dogcow.gif --q 90 Copyright (c) 1990-1994 Handmade Software, Inc. QDV --D The QDV format is used by Giffer, a Macintosh program which displays and converts image files. Syntax --D Extension .qdv Creator Steve Blackstock Used by Giffer Variations QDV files are always 8 bits per pixel. Comments Giffer is a great shareware (Beerware_, actually) program for the Macintosh that converts between various image file formats and allows viewing of graphics files. Since QDV files are always paletted, Alchemy assumes the use of the -8 option when writing QDV files. Example Convert the file input.tga to a qdv file: alchemy input.tga --D Copyright (c) 1990-1994 Handmade Software, Inc. 91 QRT Raw --T QRT files are generated by the QRT Ray Tracer, a public domain ray-tracer for Amiga, Macintosh, and IBM PC computers. Syntax --T Extension .raw Creator Steve Korn Used by QRT Ray Tracer Variations 24 bits per pixel Comments Since QRT files are always true colour, Alchemy assumes use of the -24 option when writing a QRT file. Example Convert the file spheres.gif to a QRT file called spheres.raw: alchemy spheres.gif --T 92 Copyright (c) 1990-1994 Handmade Software, Inc. RIX -R RIX files were developed by ColoRIX to use with their paint software. Syntax -R Extension .scx .rix Creator RIX Softworks, Inc. Used by ColoRIX software Variations Reads and writes Type 0 (8 bits per pixel) and Type 4 (4 bits per pixel) images. Limitations We would like to add support for Type 1 and Type 2 images but we haven't been able to find any documentation on this variation. If you have information please contact us. Comments A type 0 file will be written if there are more than 16 colours in the image; otherwise a type 4 file will be written. Since RIX files are always paletted, Alchemy assumes use of the -8 option when writing a RIX file. Example Convert the file test.gif to a RIX file: alchemy test.gif -R Copyright (c) 1990-1994 Handmade Software, Inc. 93 Scodl --s Scodl files are used by Agfa/Matrix slide recorders. Syntax --s type Parameter type: 0:Non-scalable image (pre MVP version 4.2) 1:Scalable image (MVP version 4.2 or later) The default is 0 (Non-scalable). Extension .scd Creator Agfa Corporation / Matrix Instruments Inc. Used by Agfa/Matrix slide recorders Variations Writes 8 and 24 bit run-length coded (RLC) images. Limitations Output only. Comments Agfa/Matrix made significant changes to the Scodl file format when they introduced version 4.2 of the MVP and Conductor software in 1992. Old version Scodl files could not be scaled by the MVP software; new version Scodl files can be scaled but only work the newer version of the MVP and Conductor software. Scalable Scodl images have the advantages that they do not have to be scaled to a specific output resolution and are therefore generally smaller than pre-scaled Scodl images. They can also be imaged on a film recorder with any output resolution or previewed on a monitor. The disadvantage of scalable Scodl images is that you must be using at least Scodl MVP version 4.2 and the Scodl MVP software does not perform very high-quality scaling. In particular, the MVP software only does pixel replication scaling when increasing the size of an image (this corresponds to type 'a' scaling in Alchemy) and pixel averaging when reducing the size of an image (corresponding to Alchemy 'b' scaling). 94 Copyright (c) 1990-1994 Handmade Software, Inc. Note that Alchemy pays attention to the aspect ratio or dots per inch information specified as part of the command line or present in the original image when converting to a Scodl scalable image. Therefore you should ensure that this information is correct when writing a Scodl scalable image. When writing Non-scalable Scodl files the image should be scaled up to either 2000x1366 or 4000x2732 to fill the slide. There are some limitations with the MVP software driver supplied by Agfa/Matrix: 24 bit Scodl files are not correctly interpreted by the MVP driver version 4.1 and earlier. 8 bit images are correctly interpreted. When sending very large images to the background MVP driver you must be using version 4.0 or later and have lots of EMS memory (4 megabytes is recommended). When using the foreground MVP program turning on disk caching is necessary. Examples Convert the file picture.im32 to a Scodl file using high quality scaling and preserving the aspect ratio: alchemy picture.im32 --s -Xc2000 -Yc1366 -+ Do the same thing, but generate a scalable Scodl file: alchemy picture.im32 --s1 Copyright (c) 1990-1994 Handmade Software, Inc. 95 Silicon Graphics Image (SGI) -n Silicon Graphics Image files are used by Silicon Graphics workstations. Syntax -n compressionType Parameter compressionType: 0:Verbatim (uncompressed) 1:RLE compressed The default is 0 (Verbatim). Extension .sgi Creator Silicon Graphics, Inc. Used by Silicon Graphics workstations. Variations Reads and writes 8 (gray-scale) and 24 bit verbatim (uncompressed) and RLE files. Comments Only gray-scale images may be 8 bit files. Alchemy will automatically switch to 24 bit mode when writing a colour image. Examples Convert the Sun raster file sun.im8 to a SGI file called sgiout: alchemy sun.im8 sgiout -n -. Do the same thing, but write out a RLE compressed SGI file: alchemy sun.im8 sgiout -n1 -. 96 Copyright (c) 1990-1994 Handmade Software, Inc. SPOT Image --S SPOT Image files are high-resolution satellite images produced by SPOT Image Corporation. Syntax --S Extensions For GIS (tape) format: .hdr Header information .bil Pixel data .clr Palette data [optional] For CCT (CD-ROM) format: .dat Creator SPOT Image Corp. Used by SPOT Image Corp. Variations Reads and writes 8 bits per pixel for GIS (tape) format files Reads 8 and 24 bits per pixel for CCT (CD-ROM) format files Limitations Only GIS (tape) format images are currently written; contact us if you are interested in writing CCT SPOT Image files. Comments SPOT Image GIS (tape) images are actually three files. You specify the name of the .hdr file and Alchemy automatically generates the name of the .bil and .clr files. If no palette file (.clr file) exists Alchemy will assume the image is grayscale. There may also be a statistics file with a .stx extension, but Alchemy ignores this file. When writing a SPOT file Alchemy will overwrite, without warning, existing .bil and .clr files. When reading a CCT (CD-ROM) format image specify the complete path and name of the image file. For example, on an MS-DOS system: alchemy l:\scene04\imag_04.dat -g will convert the scene 4 image to a GIF file. Copyright (c) 1990-1994 Handmade Software, Inc. 97 Example Convert the Erdas file, phoenix.lan, to a SPOT Image file: alchemy phoenix.lan --S 98 Copyright (c) 1990-1994 Handmade Software, Inc. Stork -K Stork files are CMYK images used by Stork's colour proofing machines. Syntax -K compressionType Parameter compressionType: 0:None 1:Run length coded The default is none. Extensions .idx Header information .pre Image data .tab Colour lookup table Creator Stork Colorproofing B.V. Used by Stork Colorproofing machines Variations Reads and writes 32 KCMY, 32 KCMY RLC, 16 CLU, and 16 CLU RLC images (type 100, 101, 300, and 301, respectively). Limitations Alchemy can't write paletted files with more than 256 colours. When reading paletted files with more than 256 colours they are treated as true colour. Comments Stork images are stored in two or three files (depending on whether or not there's a colour lookup table associated with the image). The filename given to Alchemy should be the name of the data file (normally with a suffix of .pre); Alchemy will generate the names of the other files by stripping the extension and appending .idx for the index file and .tab for the colour lookup table (if any). Alchemy will overwrite existing .idx and .tab files without warning when creating Stork files. Since Stork images are CMYK data files you will probably want to use an undercolour removal file to control the RGB to CMYK conversion process; see the undercolour removal file command in Chapter 8 for more information. Related options -C Undercolour Removal File Copyright (c) 1990-1994 Handmade Software, Inc. 99 Example Convert the file image.tga to an uncompressed Stork image called image.pre and image.idx, using the undercolour removal file sample.ucr: alchemy image.tga -K -Csample.ucr 100 Copyright (c) 1990-1994 Handmade Software, Inc. Sun Icon --N Sun Icon files are used by Sun Microsystems workstations to contain icon information. Syntax --N Extensions .icon .ico Creator Sun Microsystems, Inc. Used by Sun workstations Variations 1 bit, black and white. Comments This is not the same format as Sun Raster (see below). Since Sun Icon files are always black and white, Alchemy assumes use of the -8, -c2, and -b options when writing a Sun Icon file. Example Convert the sun raster file icon.im1 to a sun icon file called program.ico: alchemy icon.im1 program.ico --N Copyright (c) 1990-1994 Handmade Software, Inc. 101 Sun Raster -s Sun Raster files are used by Sun Microsystems workstations. Syntax -s compressionType Parameter compressionType: 0:None 1:Run length compression The default is None. Extensions .rast .ras .im .im1 .im8 .im24 .im32 Creator Sun Microsystems, Inc. Used by Sun workstations Variations Reads 1, 8, 24, and 32 bit Standard, BGR, RGB, and Byte Encoded (RLE) files. Writes 1, 8, 24, and 32 bit Standard files, and 1 and 8 bit Byte Encoded (RLE) files. Limitations For a short time a version of the PBM toolkit wrote Sun Raster files which had the wrong RGB order. Unfortunately there seem to be many images which were generated with this incorrect RGB order. Please be aware that Alchemy's Sun Raster reading and writing capability has been extensively tested and compared to various other tools; the RGB order we use is correct. Comments Sun Raster files are normally not compressed and so take up lots of disk space. There is no standard extension for Sun Raster files; the extensions that Alchemy uses seem to be the most common. Examples Convert the SGI file sgiout to a sun raster file called sun.im8: alchemy sgiout sun.im8 -s 102 Copyright (c) 1990-1994 Handmade Software, Inc. Do the same thing, but write out a compressed sun raster file: alchemy sgiout sun.im8 -s1 Copyright (c) 1990-1994 Handmade Software, Inc. 103 TIFF (Tagged Interchange File Format) -t TIFF is designed to be a universal raster image format. It's very popular with desktop publishing packages. Syntax -t compressionType Parameter compressionType: 0:None 1:LZW 2:PackBits 3:Group III Fax 4:Group IV Fax 5:CCITT RLE 100:None with one strip 101:LZW with one strip 102:PackBits with one strip 103:Group III Fax with one strip 104:Group IV Fax with one strip 105:CCITT RLE with one strip The default is LZW Compression. Extensions .tiff .tif Creator Aldus Corp. Microsoft Corp. Used by Various desktop publishing and scanning software. Variations Reads TIFF class B, G, R, and most class P files. Reads 1 through 8, 12, 24, and 32 bit images (ignoring the alpha channel for 32 bit images). Input compression types supported are raw, LZW, PackBits, Group III fax, Group IV fax, CCITT RLE (byte and word aligned), NeXT, Thunderscan, PICIO, and SGI RLE. Writes class B, G, P, and R files, depending on the input file and options specified. Writes 1, 4, 8, and 24 bit images. Output compression types supported are raw, LZW, PackBits, Group III fax, Group IV fax, and CCITT RLE. 104 Copyright (c) 1990-1994 Handmade Software, Inc. Limitations Class P TIFF files can only be read if they have 1, 4, or 8 bits per pixel. Comments TIFF files are often written out incorrectly; Alchemy attempts to figure out what is wrong and make intelligent decisions. If you have TIFF files which Alchemy cannot read please contact us. 1,4, and 8 bit output files are paletted unless the palette is all gray, in which case the output is a gray-scale file. When writing TIFF files using any of the fax compression types (Group III, Group IV and CCITT RLE), Alchemy uses a photometric interpretation of minIsWhite. See Appendix A, Answers to Frequently Asked Questions, for more information on writing TIFF files which conform to the various TIFF classes. LZW compression is patented by Unisys Corporation and used under license (for more information see Appendix I, Acknowledgments). Example Convert the file input.gif to an uncompressed gray-scale TIFF file called output.tif: alchemy input.gif output.tif -t0 -b Copyright (c) 1990-1994 Handmade Software, Inc. 105 Targa -a Targa files were created to support the line of Targa graphics cards. The Targa format is popular with scanners and high end paint packages. Syntax -a outputType Parameter outputType: 0:Uncompressed 1:Run Length Coded 10:Uncompressed, no footer 11:Run Length Coded, no footer The default is 0 (Uncompressed). Extension .tga Creator Truevision, Inc. Used by Various scanning and paint software. Variations Reads 8, 15, 16, 24, and 32 bit images, ignoring the alpha channel for 32 bit images. Writes 8, 15, 16, 24, and 32 bit images, writing an empty alpha channel for 32 bit images. Comments 15 and 16 bit output are actually the same except for one field in the header. Targa files allow a footer containing additional information such as aspect ratio. However some software is unable to read Targa files which have a footer, so Alchemy allows all valid combinations to be written. The most common variant for software to be able to read is 24 bit uncompressed (specify -a0 and -24). Examples Convert the file input.tif to an uncompressed 24 bit Targa file: alchemy input.tif -a -24 Convert the file input.tif to an uncompressed 15 bit Targa file called output.tga with no footer: alchemy input.tif output.tga -a10 -15 106 Copyright (c) 1990-1994 Handmade Software, Inc. Utah Raster Toolkit (RLE) --u The Utah Raster Toolkit is a set of public domain utilities for manipulating and converting images for various workstations. Syntax --u Extension .rle Creator The University of Utah The University of Michigan Used by Utah RLE toolkit Variations Reads and writes 1 and 3 channel 8 bits per pixel files; the Alpha Channel is ignored during reading. Limitations While reading, files which are 1 channel and have either no colour map or a single channel colour map are assumed to be gray-scale images. The colour map, if present, will be used as a gamma correction table. Files which are 1 channel and have a 3 channel colour map are assumed to be paletted colour files. Files which are 3 channel are assumed to be true colour. When writing RLE files Alchemy will generate a 1 channel file with a 3 channel colour map for paletted images and a 3 channel file with no colour map for true colour images. Comments The Utah Raster Toolkit is available free of charge via anonymous ftp as pub/urt-3.0.tar.Z from cs.utah.edu, weedeater.math.yale.edu, or freebie.engin.umich.edu or via floppy disk from us. Example Convert the PBM file, image.ppm, to a Utah RLE file: alchemy image.ppm --u Copyright (c) 1990-1994 Handmade Software, Inc. 107 VITec -T VITec files are used by VITec image processing software. Syntax -T Extension .vit Creator VITec Used by VITec ELT Variations Reads 8 bit grayscale and 24 bit colour files, untiled and tiled files. Writes 8 bit grayscale and 24 bit colour files untiled files. Example Convert the file map.erm to a VITec file: alchemy map.erm -T 108 Copyright (c) 1990-1994 Handmade Software, Inc. Vivid --I Vivid is a shareware ray-tracer for MS-DOS computers. Syntax --I (upper case i) Extension .img Creator Steven B. Coy Used by Vivid Ray Tracer Variations Reads and writes 24 bit RLE files. Comments The Vivid Ray Tracer is a shareware program for PCs and is available from: Stephen Coy 15205 NE 13th Pl., #2904 Bellevue, WA 98007 or from us. Example Convert the file spheres.qrt to a Vivid file: alchemy spheres.qrt --I Copyright (c) 1990-1994 Handmade Software, Inc. 109 Windows Bitmap (BMP) -w Windows BMP files are used by Microsoft Windows. Syntax -w compressionType Parameter compressionType: 0:None 1:RLE 10:Write an ICOn file The default is none. Extension .bmp Creator Microsoft Corp. Used by Microsoft Windows Variations Reads 1, 4, 8, and 24 bit RGB (raw), RLE4, and RLE8 files. Writes 1, 4, 8, and 24 bit RGB (raw), RLE4, and RLE8 files. Limitations Several of the programs which claim to read and write RLE files do not do so correctly; we do not recommend writing RLE files unless you have verified that they work with your intended application. Comments Microsoft supplied Windows utilities cannot read nor write RLE4 or RLE8 files. If you are converting an image to use as wallpaper on a 16 colour display you will want to match the palette of the output image to one of the existing 16 colour BMP images supplied with Windows (chess.bmp, for example). If you do not do this the wallpaper will not be loaded correctly. See the example section below. If you are converting an image to use as wallpaper on a 256 colour Windows 3.1 display you will want to reserve the first 8 colours. Use the -c 256 8 option to do this (see below for an example). This will force the first 8 colours of the palette to be the standard Windows colours. 110 Copyright (c) 1990-1994 Handmade Software, Inc. If you are writing a Windows icon (.ico) file you must scale the image to a width and a height of 16, 32, or 64 pixels (32 being the best choice, since Windows displays all icons as 32x32). Also, Windows seems to remap all icons to the standard 16 colours, so the best results can be obtained if you match the palette of your icons to an existing icon (see the -f option). If you don't have any other icons you can also match to one of the 16 colour wallpaper files supplied with Windows. Alchemy can write a BMP file which contains an identity palette as specified in the Microsoft Multimedia Development Kit. These images provide for quicker bitmap loading when used with the Multimedia Extensions. A palette identity file has the first and last 10 palette entries reserved for 20 system defined colours. Alchemy will write such an image if you specify -c 246 10 as part of the command line. Note that ordinarily this would produce a file which has 246 palette entries, but in this special case the file will have 256 palette entries (20 fixed by the Windows specifications and 236 chosen by Alchemy). Note that you can also specify a number smaller than 246, but the palette will always have 256 colours (since the last 10 have to occupy positions 246 through 255). Related options -c Specify number of colours -f Match to existing palette Examples Convert the image test.gif to a Windows BMP file: alchemy test.gif -w Convert the image test.gif to a 16 colour Windows BMP file to be used as wallpaper (the file chess.bmp is supplied with Windows 3.0 (substitute leaves.bmp when using Windows 3.1); this example assumes that it is in the current directory): alchemy test.gif -f chess.bmp -w Convert the image test.gif to a 256 colour Windows BMP file to be used as wallpaper with Windows 3.1: alchemy test.gif -c256 8 -w Convert the image test.gif to an icon file for use with Windows 3.1: alchemy test.gif -Xb32 -Yb32 -w 10 -f leaves.bmp Copyright (c) 1990-1994 Handmade Software, Inc. 111 Convert the image test.gif to an identity palette BMP file: alchemy test.gif -w -c 246 10 112 Copyright (c) 1990-1994 Handmade Software, Inc. WordPerfect Graphic File -W WordPerfect files are images which can be imported into WordPerfect and various other word processors and desktop publishing programs. Syntax -W Extension .wpg Creator WordPerfect Corp. Used by WordPerfect Variations 1 through 8 bits per pixel are supported. Comments In addition to raster images WordPerfect files may contain vectors and text information. Such information is lost when reading WordPerfect files. Since WordPerfect Graphic files are always paletted, Alchemy assumes use of the -8 option when writing a WordPerfect Graphic file. Example Convert the image, newpict.pcx, to a black and white WPG file: alchemy newpict.pcx -b -c2 -W Copyright (c) 1990-1994 Handmade Software, Inc. 113 XBM --b XBM files are used by the X Windowing System. XBM files are C source code files which can be read and written by various X utilities and are designed to be included in C source code for use as icons and other bit-mapped graphic images. Syntax --b Extensions .xbm .bm Creator MIT Used by The X Windowing system Variations 1 bit per pixel Limitations Because .xbm files are actually C source code files there can be many variations of .xbm files. Since adding a C preprocessor to Alchemy to handle all the theoretically allowable .xbm files is impractical we have instead designed Alchemy to interchange .xbm files with the PBM utilities and the X supplied utilities, and to read the sample .xbm files from Sun Microsystems. If you run across any .xbm files which Alchemy cannot read please contact us. The hotspot field is ignored when reading .xbm files. Since XBM files are always black and white, Alchemy assumes use of the -8, -c2, and -b option when writing a XBM file. Comments Most of the X supplied utilities (bitmap, for example) are designed to edit small .xbm images. Example Convert the file picture.im32 to an XBM file using high quality scaling and preserving the aspect ratio: alchemy picture.im32 --b -Xb64 -+ 114 Copyright (c) 1990-1994 Handmade Software, Inc. XPM --x XPM files are used by the X Windowing System. XPM files are C source code files which can be read and written by various X utilities and are designed to be included in C source code for use as icons and other bit-mapped graphic images. Syntax --x type Parameter type: 0:XBM similar style 1:XPM3 style 2:XPM2 style 10:XBM similar style with 48 bit colours 11:XPM3 style with 48 bit colours 12:XPM2 style with 48 bit colours The default is XBM similar style (see the Comments section below for a discussion of the different XPM file types). Extensions .xpm .pm Creator MIT Used by The X Windowing system Variations 8 bits per pixel Limitations Because .xpm files are actually C source code files there can be many variations of .xpm files. Since adding a C preprocessor to Alchemy to handle all the theoretically allowable .xpm files is impractical we have instead designed Alchemy to interchange .xpm files with the PBM utilities and the X supplied utilities, and to read the sample .xpm files from IBM. If you run across any .xpm files which Alchemy cannot read please contact us. Some XPM files contain colour names instead of colour values for some of the colours. The conversion information to convert these names into values is in a file supplied with the X Windowing system called rgb.txt. When needed, Alchemy will look for this table in the following directories: the current directory, /usr/lib/X11, $OPENWINHOME, and /usr/openwin/lib. If your system has the rgb.txt file in a different location you may have to copy it to the current directory (its location is system dependent; ask you system administrator if you need help finding it). Copyright (c) 1990-1994 Handmade Software, Inc. 115 Comments The different type XPM files can be identified as follows: Type 0 (XBM similar style): #define type0_format 1 ... static char *type0_colors[] = { "a", "#000000", "b", "#ff0000", ... Type 1 (XPM3 style): /* XPM */ static char * type1[] = { "32 20 12 1", "a c #000000", "b c #ff0000", ... Type 2 (XPM2 style): ! XPM2 32 20 12 1 a c #000000 b c #ff0000 ... The 48 bit colour XPM files are indentical except that the colour values are written as a 48 bit number (instead of a 24 bit number). Some software expects XPM files that have 48 bit numbers (Alchemy automatically reads either). For example: Type 10 (XBM similar style with 48 bit colours): #define type0_format 1 ... static char *type0_colors[] = { "a", "#000000000000", "b", "#ffff00000000", ... The other formats (11 and 12) are analogous. When writing an XPM file with less than 27 colours Alchemy writes 1 character XPM files, otherwise Alchemy writes 2 character XPM files. XPM files are usually quite small, therefore many utilities (the PBM toolkit for example) may have trouble reading large XPM files. 116 Copyright (c) 1990-1994 Handmade Software, Inc. Since XPM files are always paletted, Alchemy assumes use of the -8 option when writing a XPM file. Example Convert the file picture.im32 to an XPM file using high quality scaling and preserving the aspect ratio: alchemy picture.im32 --x -Xb64 -+ Copyright (c) 1990-1994 Handmade Software, Inc. 117 XWD --w XWD is the file format used by xwd, the X window dumping utility. Syntax --w type Parameter type: 0:Z type 1:XY type The default is Z type. Extension .xwd Creator MIT Used by The X Windowing System Variations Reads 1, 4, 8, and 24 bits per pixel Z format and 1, 4, and 8 bit XY format XWD files. Writes 1, 8, and 24 bits per pixel Z format and 1 and 8 bit XY format XWD files. Example Convert the XBM file, icon.xbm, to an XWD file: alchemy icon.xbm --w 118 Copyright (c) 1990-1994 Handmade Software, Inc. 5 General Options ------------------------------------------------------------------------ Introduction General options are options which do not affect the conversion of the image. They control such things as the overwriting of existing files and the way that memory is used. Copyright (c) 1990-1994 Handmade Software, Inc. 119 Conserve Memory -$ Purpose Use as little memory as possible when converting images. Syntax -$ (dollar sign) Comments Normally Alchemy tries to work on chunks of the image several lines long to improve performance. Use of the -$ option will cause it to use the smallest size chunks possible for the conversion being performed. On MS-DOS based systems using the standard version of Alchemy this will usually allow conversion of larger images than would otherwise be possible. On UNIX systems and in the 386 Enhanced version of Alchemy this may reduce paging when converting very large images. Example Convert the image giant.tga to a TIFF file conserving memory: alchemy giant.tga -$ -t 120 Copyright (c) 1990-1994 Handmade Software, Inc. Display Image Stats -x Purpose Display image statistics. Syntax -x Comments Displays image type, size, number of colours, aspect ratio, resolution, and compression ratio. Example Find out about the image called image.tga: alchemy -x image.tga Copyright (c) 1990-1994 Handmade Software, Inc. 121 Do Not Alter Output Filename -. Purpose Disable automatic appending of the output image type to the output file name. Syntax -. (period) Comments By default, if there's no '.' in the output filename, Alchemy will add an extension indicating the type of file. If the -. option is specified no extension will be added. This is most useful on non-MS-DOS systems where '.' is not a special character in filenames. Example Convert the file called infile.gif to a PCX file called outfile (if you did not use the -. option Alchemy would automatically change the output file name to outfile.pcx): alchemy infile.gif outfile -p -. 122 Copyright (c) 1990-1994 Handmade Software, Inc. Help -h Purpose Give you information on how to use Image Alchemy. Syntax -h option Parameter option: 0:General help 1:General options 2:Output formats A through L 3:Output formats M through Z 4:Colour options 5:Scaling options 6:Display options (MS-DOS Only) 7:PostScript input options Default is 0, general help Limitations The help option cannot be combined with any other options. Comments The help information given by this command is only a summary. The numbers in braces after the command name refer to the page numbers in this manual. Related options -? support and update information Example Get help on the colour options: alchemy -h4 Copyright (c) 1990-1994 Handmade Software, Inc. 123 Override Input Type -= Purpose Force Alchemy to treat the input file as the specified file type. This can be used if Alchemy cannot identify or misidentifies the format of an input image. Syntax -= inputType Parameter The inputType must be a valid number identifying a supported format. The inputTypes are as follows: ADEX..............24 Macintosh PICT....10 Alpha BMP.........42 MacPaint..........49 Autologic.........28 MTV...............17 AVHRR.............43 OS/2 BitMaP.......55 Binary (BIF)......31 PCPaint/Pictor....29 Calcomp...........50 PCX................9 CALS..............41 PDS...............37 Core IDC..........66 Portable BitMap...13 Cubicomp PM.......44 Puzzle............51 Dr. Halo CUT......45 Q0................21 ER Mapper Raster..59 QDV...............18 Erdas Image.......19 QRT Raw...........20 First Publisher...46 RIX...............38 Gem VDI Image.....22 SGI Image.........11 GIF................1 Spot Image........39 GOES..............40 Stork.............32 Hitachi Raster....63 Sun Icon..........52 HP PCL............15 Sun Raster.........8 HP-48sx GROB......60 Targa..............6 HSI JPEG..........30 TIFF...............4 HSI Palette........3 Utah RLE..........23 HSI Raw............5 VITec.............64 IBM Picture Maker.48 Vivid IMG.........16 IFF/ILBM...........7 Windows BitMaP....12 Img Software Set..61 WP................27 Jovian VI.........36 X BitMap (XBM)....35 JPEG...............2 X PixMap (XPM)....47 Lumena CEL........62 XWD...............33 Comments Rarely will Alchemy misidentify a file; the file is usually damaged in some way when this happens. If the file is damaged, or if you specify an input type that does not correspond to the actual type of the image, the results will be unpredictable. Example Convert the file unknown.xxx to an OS/2 Bitmap file called output.bmp, forcing unknown.xxx to be treated as a Sun Raster image: alchemy unknown.xxx output.bmp -O -=8 124 Copyright (c) 1990-1994 Handmade Software, Inc. Overwrite -o Purpose Allow Alchemy to overwrite existing files on the disk. Syntax -o Comments Image Alchemy will not overwrite an existing file unless the -o option is specified. Limitations The input file name and the output file name cannot be the same. Example Convert the file input.tga to a GIF file called output.gif, overwriting the existing file called output.gif: alchemy input.tga output.gif -g -o Copyright (c) 1990-1994 Handmade Software, Inc. 125 Program information -? Purpose Give you information on how to get support for Image Alchemy or inquire about update information. Syntax -? Comments UNIX users have to escape the question mark with a back-slash (instead of -? use -\?). This is because the UNIX shell will attempt to perform wildcard expansion on the question mark. Limitations The information option cannot be combined with any other options. Related options -h help with commands Example Get support information: alchemy -? 126 Copyright (c) 1990-1994 Handmade Software, Inc. Quiet -Q Purpose Suppress all status messages (but not error messages). Syntax -Q Comments This is useful when running Alchemy in the background on UNIX systems or in batch files on MS-DOS systems (and you don't want the output of Alchemy scrolling important messages off of the screen). Limitations There is no way to suppress error messages. Example Convert the file dummy.gif to a PCX file but don't report any status messages: alchemy dummy.gif -Q -p Copyright (c) 1990-1994 Handmade Software, Inc. 127 Warnings --W Purpose Treat missing input files, unidentifiable input files, and non-overwriteable output files as a non-fatal errors. Syntax --W Comments When used in conjunction with the Wildcard option (see below) the Warnings option allows Alchemy to proceed even when certain error conditions occur. Specifically, any input files which are missing or can't be identified as valid image files and any output files which already exist but are not to be overwritten are skipped and processing continues with the next file. At the end of processing Alchemy displays lists of the files which were not found, which could not be identified, and which already existed but could not be overwritten. This option was added at the request of our customers who routinely convert large numbers of files and don't want Alchemy to stop if it finds a file missing or finds that an output file already exists. Limitations Any errors which occur during the processing of an image file are always fatal. This option can only be used with the Wildcard option. Examples Convert all the GIF files in the current directory to JPEG files, skipping any files which can't be identified or already have existing JPEG files: alchemy -- *.gif -j --W 128 Copyright (c) 1990-1994 Handmade Software, Inc. Wildcard -- Purpose Allow the conversion of multiple files with a single execution of Alchemy. Syntax -- (dash) Comments The wildcard option allows you to specify multiple file names and file names which include wild card characters. Alchemy will perform the same conversion for each input file name that it finds. On MS-DOS systems the use of the wildcard option (--) is not required if the first file name specified includes a wildcard character (* or ?); however to reduce confusion it is still recommended. Limitations The wildcard option (--) must be specified before any file names. If you are using the wildcard option you may not specify an output file name; the file names are automatically generated by substituting an appropriate extension to the input file names. If you do specify an output file name it will be misinterpreted as another input file. An output path name may specified and all output files will be stored there (see the Examples section below for an example of this). Any error will terminate the execution of Alchemy; any images which appear in the filename list after the one causing the error will not be processed. This includes attempting to overwrite an already existing file without specifying the -o option. If you use the --W option in conjunction with wildcards certain errors will be treated as warnings and not cause Alchemy to terminate. These errors are: missing input files, input files which could not be identified, and output files which already existed but could not be overwritten (because the -o option was not specified). Copyright (c) 1990-1994 Handmade Software, Inc. 129 Alchemy does not intelligently retain information between files. For example, if you are matching a group of files to an existing palette, the inverse palette generation step only needs to be performed once, but it is in fact done for each file. This only affects the speed of conversions, not the quality. Examples Convert all the GIF files in the current directory to JPEG files: alchemy -- *.gif -j Convert all the TIFF files in the directory \tiff to PCX files in the directory \images\output: alchemy -- \tiff\*.tif -p \images\output Convert all the GIF files in the current directory, in the directory \images, and in the directory \more to GIF files, scaling them to be no larger than 640x480 and write them to the directory \small: alchemy -- *.gif \images\*.gif \more\*.gif -g -Xb640 -Yb480 -+ \small Convert the files madonna.gif, bay4.gif, everest.tga, and basil.tif to JPEG files, overwriting any existing files: alchemy -- madonna.gif bay4.gif everest.tga basil.tif -o -j Convert the files test1.tif, test2.tif, and new*.gif to ILBM files, matching them to the palette from the file output.pal: alchemy -- test1.tif test2.tif new*.gif -f ou tput.pal -i 130 Copyright (c) 1990-1994 Handmade Software, Inc. 6 Colour and Palette Options ------------------------------------------------------------------------ Introduction Colour and Palette options are options which affect the appearance of the output image. They control such things as the number of colours in the output image and the dithering techniques used. Copyright (c) 1990-1994 Handmade Software, Inc. 131 Black and White -b Purpose Convert the image to black and white or gray- scale. Syntax -b Comments The -b option causes an image to be converted to either black and white or gray-scale, depending on the use of the -c option. If -c2 is specified the output image will be black and white. Any other number of colours specified with -c will cause Alchemy to generate a gray scale file with that many shades of gray in the output image. If the - c option is not used the default is to write a file with 256 shades of gray when converting from a true colour image. When converting from a paletted image the number of shades of gray defaults to the number of colours in the original image. The shades of gray are uniformly distributed from 0 to 255. When converting from true colour the image will be changed to a paletted image unless the -24 option is used. Related options -8 Paletted output -24 True colour output -c Specify number of colours Examples Convert the file sample.jpg into a 256 shades of gray raw file: alchemy sample.jpg -b -r Convert the file madonna.jpg into a 4 shades of gray gif file called gray.gif: alchemy madonna.gif gray.gif -b -c4 -g 132 Copyright (c) 1990-1994 Handmade Software, Inc. Colours -c Purpose Specify the number of colours for the output file. Syntax -c colours [reserveColours] Parameters colours: Specifies the number of colours in the output image. May be between 2 and 256. reserveColours: Specifies the number of colours to reserve in the output image. May be between 0 and 255. Comments If the input file has a larger number of colours than specified for the output file, the image will be quantized using Heckbert's median cut algorithm and dithered. For further information on Heckbert's median cut algorithm see Appendix B, Colour and Dithering. The number of colours to reserve is an optional parameter. If it is present it causes the specified number of colours to be reserved from the beginning of the palette. The output image will not contain any of those colour indices. This can be useful if you have menus or other information you wish to display at the same time as the images and they use colours at the beginning of the palette. The menu colours will then not interfere with the image. The first indices are set to black unless 16 is specified, in which case they are set to the standard VGA colour palette. Limitations Specifying the number of colours only has an effect if you are writing a paletted file (using the -8 option) or if the output file type is always paletted. Converting an image with a large number of colours to a small number of colours (less than 8) will usually give poor results. The reserved colours will be set to black unless 16 colours are reserved. In that case they will be set to the standard VGA colours. Related options -8 Convert to paletted image -d Specify dither type -u Use uniform palette Copyright (c) 1990-1994 Handmade Software, Inc. 133 Examples Convert the image colours.gif into a 16 colour PCX file called colour16.pcx alchemy colours.gif colour16.pcx -p -c16 Convert the image colours.tga into a 256 colour GIF file called output.gif, reserving the first 16 colours. alchemy colours.tga output.gif -g -c256 16 134 Copyright (c) 1990-1994 Handmade Software, Inc. Dither -d Purpose Specifies the type of dithering to apply to the image. Syntax -d[s] ditherType [perturbation] Parameters If the -d is immediately followed by an 's', then a serpentine raster is used. ditherType: 0:None 1:Floyd-Steinberg 2:Stucki 3:Jarvis, Judice, & Ninke 4:Stevenson and Arce 5:Sierra Lite 20:Halftone (clustered dot) 21:Bayer (dispersed dot) 22:Halftone 2 (clustered dot) The default is Floyd-Steinberg. perturbation: 0 through 127 The default is 0. Comments Dithering is used to reduce colour banding in an image caused by the palette not having a perfect match for every colour in the image. Types 1 through 5 are all error-diffusion dithers. Types 1 and 5 are the fastest of the diffusion dithers, and they usually look the best on low resolution devices like CRTs. Types 2, 3, and 4 all tend to cause an image to appear more grainy on low resolution output devices (such as CRTs). However, they produce better results than types 1 or 5 on high-resolution, low colour output devices such as laser printers or 1 bit CMYK plotters. Type 22 is a digital halftone; this will produce the most accurate grays on a laser printer, but the image won't be as sharp as one produced by the error-diffusion dithers. Type 21 is a dispersed dot ordered dither; it's only advantage over the error-diffusion algorithms is speed. Type 20 is an additional halftone pattern. It's similar to type 22, but with a coarser screen. Copyright (c) 1990-1994 Handmade Software, Inc. 135 The -d option only has an effect if the number of colours is being reduced or the image is being re- mapped to a new palette. Specifying a perturbation adds noise to the image, which can help break up visible patterns introduced by dithering. The parameter specifies the magnitude of the noise. Perturbation has no effect on dither types 20, 21, and 22. Using a serpentine raster can also help to reduce visible patterns introduced by dithering. Using a serpentine raster has no effect on dither types 20, 21, and 22. In general we use -d1 when converting 24 bit images to 8 bit paletted, and -ds3 when converting colour images to black and white and 1 bit CMYK (for sending to a laser printer or plotter). Examples Convert the 256 colour file image.gif to a 16 colour PCX file using a uniform palette and no dithering: alchemy image.gif -p -c16 -d0 -u Convert the true colour image sample.jpg into a 256 colour GIF file called sample.gif, using Stucki dithering: alchemy sample.jpg -g -d2 Convert the 256 colour image sample.gif into a one bit black and white PCL file called sample.pcl, using Jarvis, Judice, and Ninke dithering, a serpentine raster, and a little noise: alchemy sample.gif -P -b -c2 -ds3 20 136 Copyright (c) 1990-1994 Handmade Software, Inc. EGA Palette -E Purpose Optimize the image quality for display on an EGA board and monitor. Syntax -E Comments If you are converting images to display on an EGA board and monitor this option will optimize the image quality. This option reduces the palette resolution to two bits and automatically specifies the following: -8 -c16 -z0 2 0. Limitations The number of colours in an EGA palette must be less than or equal to 16; the number of colours defaults to 16 but can be reduced by using the -c option. Related options -c specify number of colours Example Convert the image dave1.tga into dave1.pcx, a PCX file with a palette optimized for EGA use: alchemy dave1.tga -E -p Copyright (c) 1990-1994 Handmade Software, Inc. 137 False Colour -F Purpose False colour an image using the palette from a file. The input image will be changed to use the palette found in the specified filename but no attempt at picking the best match will be done. Syntax -F filename Parameter filename: Any valid image file which contains a palette. Comments This feature can be used to add false colour to monochrome images. The output file is not dithered. False colour may only be used with paletted input files. Limitations Cannot be combined with the spiff (-S) or match palette (-f) options. Example False colour the file scan.gif using the palette from the file colorful.pcx, creating the GIF file new.gif: alchemy scan.gif new -F colorful.pcx -g 138 Copyright (c) 1990-1994 Handmade Software, Inc. Gamma correction -G Purpose Specify the gamma of an input, output, or palette file and/or perform gamma correction. Syntax -G gammaType gammaValue Parameters gammaType: i:Specify input gamma o:Specify output gamma p:Specify gamma of palette gammaValue: 0.0 to 4.0 Comments To perform gamma correction, Alchemy needs to know both the input and output gamma. For some file formats the gamma is known; if you're reading a file with known gamma, such as JPEG, PICT, PCPAINT, or a Targa file with a gamma field, you don't need to specify the input gamma. Likewise, if you're writing a file which has a fixed gamma you don't need to specify an output gamma. Even if reading or writing a file format which has a known gamma you may override it by using the -Gi or -Go option. However, even if both input and output gamma are known based on the input file and the output format, you must still enable gamma correction for any correction to take place; you can do this with just '-G' (if you had specified input, output, or palette gamma, this would be implied). This is because there are quite a few images around that have specified or implied gammas that are wrong, which could cause Alchemy to make matters worse instead of better. Typical gamma values are 1.0 for images from Macintoshes and 2.2 for images from PCs. Examples To convert the Mac PICT file test.pic, which has a gamma of 1.0, to a PCX file for use on a PC (which should have a gamma of 2.2), use: alchemy test.pic -p -Gi1.0 -Go2.2 Copyright (c) 1990-1994 Handmade Software, Inc. 139 In this example the input gamma could have been omitted, as PICT files have an implied gamma of 1.0, but it's best to include it to reduce confusion. To convert the file image.tga, which has a gamma of 2.2, to a GIF file for use on a Mac, matching the palette test.pal which was created with a gamma of 1.5: alchemy image.tga -g -Gi2.2 -Go1.0 -Gp1.5 - ftest.pal 140 Copyright (c) 1990-1994 Handmade Software, Inc. Match Palette -f Purpose Match the output to a palette read from a file. The input image will be re-mapped to use the palette found in the specified file. Syntax -f filename Parameter filename: Any valid image file which contains a palette Comments Using the -f option will cause the output image to be dithered (unless you specify no dithering by using the -d0 option). The -f option can be useful if you are combining several images into a collage or want to match an image to a pre-existing palette. You can also create a custom palette from scratch by using a text editor and creating a .PAL file. Limitations Cannot be combined with the spiff option (-S) or the false colour option (-F). The number of colours in the final image will be equal to the number of colours in the palette being read in. The specified file must contain a palette (i.e. cannot be true colour). Related options -l Generate palette file -F False colour -d Dither Examples Convert the image bigimage.tif to a pcx file using the palette from the file standard.pal: alchemy bigimage.tif -p -f standard.pal Convert the image colour.gif to a gif file called colour2.gif using the palette from the file newpal.gif: alchemy colour.gif colour2 -fnewpal.gif -g Copyright (c) 1990-1994 Handmade Software, Inc. 141 Negate -N Purpose Changes the image to a negative. Syntax -N Comments This option is equivalent to a photographic negative. When used on black and white images black is changed to white and white is changed to black. On colour images each of the Red, Green, and Blue channels are inverted separately (so that bright blue will become bright yellow). Example Negate the file sample.gif, generating a GIF file called negative.gif: alchemy sample.gif negative -N -g 142 Copyright (c) 1990-1994 Handmade Software, Inc. Palette -8 Purpose Force the output image to be paletted. Syntax -8 Comments This option is -8 because paletted images are typically 8 bits per pixel. Alchemy defaults to the -8 option if the input file is paletted or gray-scale. Some file formats require files to be paletted; for those formats the -8 option is assumed. Some file formats do not have a paletted variation; in those cases the -8 option will be ignored if specified. Some file formats only allow gray- scale files to be 8 bit; in those cases Alchemy will ignore the -8 option if the image being written is not gray-scale. The actual number of bits per pixel is determined by the -c option (below). If the input file is true colour the output file will be quantized and dithered (see the -c and -d options below). Related options -15 True colour output -16 True colour output -24 True colour output -32 True colour output -c specify number of colours in image -d dither Examples Convert the JPEG file bigimage.jpg into a paletted TIFF file with 256 colours: alchemy bigimage.jpg -8 -t Convert the Targa file madonna.tga to a 16 colour PCX file (note that the -8 option is implied by the use of the -c16 option): alchemy madonna.tga -c16 -p Copyright (c) 1990-1994 Handmade Software, Inc. 143 Palette Selection -z Purpose Control how the palette is generated. These options only have an effect if the palette is being generated by Alchemy using Heckbert's median cut algorithm. Most of the time you do not need to use these options. Alchemy will automatically generate the best palette possible. Contact us for further information if you intend to use the -z option. Syntax -z sortType [selectionType [swapType] ] Parameters sortType: 0:None 1:Popularity 2:Luminance (white to black) 3:RGB 4:Luminance (black to white) The default is None. selectionType: 0:Mean 1:Median 2:Corner The default is Mean. See Appendix B, Colour and Dithering, for an explanation of these choices. swapType: 0:None 1:IBM (colour 0 is black, 7 is white) 2:Macintosh (colour 0 is white, 255 is black) 3:Sun (colour 0 is white, 1 is black) The default is based on the file type being written out (IBM for GIF, Macintosh for Mac PICT, Sun for Sun Raster, and None for all others). 144 Copyright (c) 1990-1994 Handmade Software, Inc. Comments The most common use for this option is to sort the palette; in this case only a single parameter is needed. This option only affects palettes that are generated by Alchemy. To sort an existing palette you can save the image as a true colour file (such as HSI Raw, by using the -24 -r options) and then convert that back to a paletted file, specifying the desired sort type. In most cases this will not change the image (other than the palette order); however if the palette had entries representing colours that are nearly identical then the image may be modified. Limitations Note that it is not possible to specify a swapType without first specifying both a sortType and a selectionType. See Appendix B, Colour and Dithering, for more information. Example Convert the file input.tga to a gif filed called output.gif sorting the colours by luminance, using the mean of the Heckbert box for the colour, and moving the colours around so that the lightest colour is colour 0 and the darkest colour is colour 1. alchemy input.tga output.gif -g -z4 0 3 Copyright (c) 1990-1994 Handmade Software, Inc. 145 Spiff -S Purpose Enhance the image contrast by stretching the pixel colour values to the full 0 to 255 range. Syntax -S spiffType Parameter spiffType: a:Histogram stretching b:Histogram linearization c:Histogram stretching with black and white ignored The default is Histogram stretching. Comments This command can be used if the image you are converting is shifted in brightness or squished in contrast. This can happen if you scan or digitize a very dark or very bright image. The default type, histogram stretching, simply insures that the image has pixels which are distributed over the entire output range (0 to 255). Histogram linearization insures that the distribution of pixels over the output range is linear. Type c spiffing is identical to type a spiffing except that the colours absolute black and absolute white are ignored in the image. This is useful when you have images which have black borders or white captions, since type a spiffing would treat these as part of the image data and not perform any spiffing. Histogram linearization can produce significantly better results than histogram stretching for some images. Generally you will want to try both types to see which gives better results. Limitations The -S option cannot be used at the same time as the -b option when converting from a true colour image. A work around is to do the operation in two steps, converting it to black and white first and then spiffing the resulting image. 146 Copyright (c) 1990-1994 Handmade Software, Inc. Using the spiff option at the same time as the match palette, -f, or false colour, -F, options is not allowed. This is because the spiff option would be performed before the palette is changed, which would nullify the effects. A work around is to do the matching or false colouring first, and then spiff the resultant image. Related options -b Black and White -f Match palette -F False colour image Examples Convert the file gloomy.pcx into a PCX file called better.pcx: alchemy gloomy.pcx better.pcx -S -p Do the same thing using histogram linearization instead of histogram stretching: alchemy gloomy.pcx better.pcx -Sb -p Copyright (c) 1990-1994 Handmade Software, Inc. 147 True Colour (15 bits) -15 Purpose Force the output image to be true colour, 15 bits (5 bits per component). Syntax -15 Comments See the True Colour (24 bits) section, below. Related options -8 Paletted output -16 True colour output (16 bits) -24 True colour output (24 bits) -32 True colour output (32 bits) Example Convert the GIF file test.gif into an uncompressed, true colour 15 bit Targa file called test.tga: alchemy test.gif -a0 -15 148 Copyright (c) 1990-1994 Handmade Software, Inc. True Colour (16 bits) -16 Purpose Force the output image to be true colour, 16 bits (5 bits each for red and blue, 6 for green). Syntax -16 Comments See the True Colour (24 bits) section, below. Related options -8 Paletted output -15 True colour output (15 bits) -24 True colour output (24 bits) -32 True colour output (32 bits) Example Convert the GIF file test.gif into an uncompressed, true colour 16 bit Targa file called test.tga: alchemy test.gif -a0 -16 Copyright (c) 1990-1994 Handmade Software, Inc. 149 True Colour (24 bits) -24 Purpose Force the output image to be true colour, 24 bits (8 bits per component). Syntax -24 Comments This option is -24 because true colour images are typically 24 bits per pixel. Some file formats require files to be true colour; for those formats the -24 option is assumed. Some file formats only have a paletted variation; in those cases the -24 option will be ignored if specified. The file formats which may be either true colour or paletted default to true colour if the input file is true colour. Certain file formats may only be paletted if the images are gray-scale, in those cases Alchemy will automatically switch to true colour if the output image is colour. Converting a paletted image to true colour will not improve its quality or change its appearance. The primary use of this option is to force an image to be true colour when converting to a format which allows either paletted or true colour, but where the paletted variation is not well supported (like the Targa image format). If the file format you are converting to does not have a 24 bit mode the closest true colour mode available will be chosen, in the following order: 32 bit, 16 bit, 15 bit. Related options -8 Paletted output -15 True colour output (15 bits) -16 True colour output (16 bits) -32 True colour output (32 bits) Example Convert the GIF file test.gif into an uncompressed, true colour Targa file called test.tga: alchemy test.gif -a0 -24 150 Copyright (c) 1990-1994 Handmade Software, Inc. True Colour (32 bits) -32 Purpose Force the output image to be true colour, 32 bits (8 bits per component, 8 bits for the alpha channel). Syntax -32 Comments See the True Colour (24 bits) section, above. Related options -8 Paletted output -15 True colour output (15 bits) -16 True colour output (16 bits) -24 True colour output (24 bits) Example Convert the GIF file test.gif into an uncompressed, true colour 32 bit Targa file called test.tga (the alpha channel will be empty): alchemy test.gif -a0 -32 Copyright (c) 1990-1994 Handmade Software, Inc. 151 Undercolour Removal -C Purpose Control the undercolour removal process, colour correction, and density correction for output formats which use the CMYK colour space. You will probably want to use an undercolour removal file when converting images to a format which uses the CMYK colour space. Syntax -C filename Parameter filename: The name of the file which contains the undercolour removal information Comments The undercolour removal portion of the file is compatible with the format used by Stork Colorproofing B.V. The format of this file is described in Appendix G, Undercolour Removal Files. Sample undercolour removal files can be found in the samples directory on the Alchemy distribution disk or tape. We are also developing additional UCR files for use with specific devices; contact us for more information. Example Convert the file image.tga to an HP RTL file called image.rtl using the undercolour removal file sample.ucr: alchemy image.tga --r4 -Csample.ucr 152 Copyright (c) 1990-1994 Handmade Software, Inc. Uniform Palette -u Purpose Use a Uniform Palette. Syntax -u Comments Instead of using the Heckbert median cut algorithm to generate a custom palette for the image, use a palette with entries which are evenly distributed in the RGB colour cube. The advantage of using a uniform palette is that it's faster than generating a custom palette. However, this is at the expense of image quality since the palette isn't generated based on image content. When just viewing a true colour image on a paletted display a uniform palette is used. The -c option can be used in conjunction with -u to specify the size of the uniform palette; in that case Alchemy will generate a palette with not more than the specified number of colours (but not less than 8). Limitations The palette size will not necessarily match the specified size, as the actual size must be the product of three integers. Alchemy picks integers that roughly correspond to the sensitivity of the human eye to red, green, and blue (30%, 59%, and 11%). Related options -c Specify number of colours -d Dither type Examples Convert the file many.tga to a gif file using a 256 colour uniform palette: alchemy many.tga -g -u Convert the file many.tga to a gif file with up to 128 colours in a uniform palette: alchemy many.tga -g -u -c128 Copyright (c) 1990-1994 Handmade Software, Inc. 153 154 Copyright (c) 1990-1994 Handmade Software, Inc. 7 Scaling Options ------------------------------------------------------------------------ Introduction These options are all related to raster image scaling. Copyright (c) 1990-1994 Handmade Software, Inc. 155 Flip Image -^ Purpose Flip image vertically (turn image upside-down) Syntax -^ (caret) Comments Causes the image to be turned upside-down. May be combined with the mirror image option (see below) to cause the image to be rotated 180 degrees. Related options --^ Mirror image Example Convert the Targa file head.tga to another Targa file called tail.tga: alchemy head.tga tail.tga -a -^ 156 Copyright (c) 1990-1994 Handmade Software, Inc. Mirror Image --^ Purpose Flip image horizontally (mirror image) Syntax --^ (caret) Comments Causes the image to be mirrored. May be combined with the flip image option (see above) to cause the image to be rotated 180 degrees. Related options -^ Flip image Example Convert the Targa file left.tga to another Targa file called right.tga: alchemy left.tga right.tga -a --^ Copyright (c) 1990-1994 Handmade Software, Inc. 157 Offset Image -_ Purpose The offset image option changes the position of the image on the page. It only effects printer and plotter formats. Syntax -_ xOffset[units] yOffset[units] (underscore) Parameter xOffset: The amount to shift the image horizontally. yOffset: The amount to shift the image vertically. units: The units each size parameter is in: p:Pixels i:Inches c:Centimeters units is optional; the default is pixels. The units value must immediately follow the appropriate offset parameter. Comments The offset is measured from the upper left corner for Calcomp, HP PCL, and HP RTL files and from the lower left corner for EPS files. Limitations Only works for those output options that support an offset. These are Calcomp, EPS, HP PCL, and HP RTL. If you specify the offset in inches or centimeters you must also specify a dots per inch value. Example Convert the image temp.gif to an HP PCL file at 300 DPI, positioning it on the page 1 inch from the top and 200 pixels from the left: alchemy temp.gif -P -_ 200 1i -D300 300 158 Copyright (c) 1990-1994 Handmade Software, Inc. Preserve Aspect Ratio -+ Purpose Preserve aspect ratio when scaling. Syntax -+ (plus) Comments If specified with either the -X or -Y option Alchemy will choose the other dimension to preserve the aspect ratio of the image. If specified in conjunction with both -X and -Y Alchemy will use the values specified as a bounding box, reducing one dimension if necessary to preserve the image aspect ratio. Limitations Does not pay attention to the pixel aspect ratio values in the input image. Related options -X Scale image in horizontal dimension -Y Scale image in vertical dimension Examples Change the size of the image toobig.gif so that the width is 640 and the height is the correct number to preserve the aspect ratio of the image (the new image will be called notbig.gif): alchemy toobig.gif notbig -X640 -+ -g Do the same thing but guarantee that the image will not be larger than 640 by 480: alchemy toobig.gif notbig -X640 -Y480 -+ -g Do the same thing but use better quality scaling: alchemy toobig.gif notbig -Xb640 -Yb480 -+ -g Copyright (c) 1990-1994 Handmade Software, Inc. 159 Scale Image in Horizontal Direction -X Purpose Scale the horizontal dimension of the image to the specified size. Syntax -X[scaleType] size[units] Parameters scaleType: The type of scaling to use: a:Nearest Neighbor b:Averaging/Linear Interpolation c:Lanczos2 d:Lanczos3 scaleType is optional; the default is Nearest Neighbor. The higher the scale type the higher the quality (and the longer the processing time). size: The size of the output image in the horizontal dimension. units: The units the size parameter is in: p:Pixels i:Inches c:Centimeters x:Factor units is optional; the default is pixels. The units value must immediately follow the size parameter. Comments Nearest neighbor type scaling is faster than the other types but introduces aliasing (which reduces image quality). The highest quality scaling supported is lanczos3, but it takes much longer than averaging/linear interpolation and usually doesn't produce significantly better results. Specifying a units value of x causes the size parameter to be treated as a scale factor; e.g. - X 2.5x scales the image by a factor of 2.5 in the X direction. If you specify a units for the image size in inches or centimeters you must specify a dots per inch value for the output image. 160 Copyright (c) 1990-1994 Handmade Software, Inc. Limitations All of the scale types other than nearest neighbor give much better results than nearest neighbor scaling, but they are slower and require a new palette to be generated for paletted output files (you can force alchemy to use the original palette by using the -f option and specifying the original image as the palette file). Related options -Y Scale in vertical dimension -+ Preserve aspect ratio -D Specify image resolution Examples Scale the input image, test.gif, to 640 by 480 using good quality scaling, calling the output file test2.gif: alchemy test.gif test2.gif -Xb640 -Yb480 -g Scale the input image, big.tga, using fast scaling to an image which is 320 pixels across and the same aspect ratio as the input image, calling the output file out.tga: alchemy big.tga out -X320 -+ -a Scale the input image, oddsize.gif, using the highest quality scaling, to an image which is no larger than 640x480, but has the same aspect ratio as the original image, calling the output image new.gif: alchemy oddsize.gif new.gif -Yd480 -Xd640 -+ -g Do the same thing as the previous example, but retain the same palette: alchemy oddsize.gif new.gif -Yd480 -Xd640 -+ -g -f oddsize.gif Scale the input image, test.gif, to 2.5 times its original size in both dimensions using good quality scaling, calling the output file test2.gif: alchemy test.gif test2 -Xb2.5x -Yb2.5x -g Scale the input image, silly.tga, to 1/3 its original size in the X dimension and 1/4 the original size in the Y dimension, using low quality scaling in the X dimension and very high quality scaling in the Y dimension, calling the output file test.tga: alchemy silly.tga test -a -Xa.33x -Yd0.25x Copyright (c) 1990-1994 Handmade Software, Inc. 161 Scale, using type b scaling, the input image, test.jpg, to 3" x 4.5" inches writing a 300 DPI HP PCL file: alchemy test.jpg -P -Xb3i -Yb4.5i -D300 300 Print all JPEG images in the current directory to an HP LaserJet at 300 DPI, using dither type 22, scaling the images to fill the page and preserving aspect ratio (we use 8.16" x 10.66" inches as the printable area since the printer has a 1/6" border on all four edges): alchemy -- *.jpg -P -Xb8.16i -Yb10.66i -+ -D300 300 -d22 162 Copyright (c) 1990-1994 Handmade Software, Inc. Scale Image in Vertical Direction -Y Purpose Scale the vertical dimension of the image to the specified size. Syntax -Y[scaleType] size[units] Parameters scaleType: The type of scaling to use: a:Nearest Neighbor b:Averaging/Linear Interpolation c:Lanczos2 d:Lanczos3 scaleType is optional; the default is Nearest Neighbor. The higher the scale type the higher the quality (and the longer the processing time). size: The size of the output image in the vertical dimension. units: The units the size parameter is in: p:Pixels i:Inches c:Centimeters x:Factor units is optional; the default is pixels. The units value must immediately follow the size parameter. Comments Nearest neighbor type scaling is faster than the other types but introduces aliasing (which reduces image quality). The highest quality scaling supported is lanczos3, but it takes much longer than averaging/linear interpolation and usually doesn't produce significantly better results. Specifying a units value of x causes the size parameter to be treated as a scale factor; e.g. - Y 2.5x scales the image by a factor of 2.5 in the Y direction. If you specify a units for the image size in inches or centimeters you must specify a dots per Inch value for the output image. Copyright (c) 1990-1994 Handmade Software, Inc. 163 Limitations All of the scale types other than nearest neighbor give much better results than nearest neighbor scaling, but they are slower and require a new palette to be generated for paletted output files (you can force alchemy to use the original palette by using the -f option and specifying the original file name). Related options -X Scale in horizontal dimension -+ Preserve aspect ratio -D Specify image resolution Examples See the -X option, Scale Image in Horizontal Direction, above, for examples. 164 Copyright (c) 1990-1994 Handmade Software, Inc. Specify Image Aspect Ratio -D Purpose Specify aspect ratio for the output image. Syntax -D aspectRatio Parameter aspectRatio: The percentage of the width of a pixel to its height. Comments This option does not actually change the aspect ratio of the image, it just adds the aspect ratio value to the output file. This is important when trying to export the image to software which expects this information. The aspect ratio of an image is the ratio of the width of a single pixel to the height of a single pixel. (So to specify an aspect ratio of 5:6 use -D 83, since (5/6)*100 is 83). Alchemy attempts to preserve the aspect ratio value when converting images whenever one is found in the input image, but since so few file formats have aspect ratio information this hardly ever happens. To write an output image without aspect ratio information specify an aspect ratio of 0 (zero). This option also has an effect when using the MS- DOS version of Image Alchemy and displaying images. Limitations It is not possible to specify both an aspect ratio and a dots per inch value for an image. This is because specifying a dots per inch value implies an aspect ratio. Many file types do not have an aspect ratio value; specifying one when writing such a file type will have no effect. Related options -D Specify resolution Copyright (c) 1990-1994 Handmade Software, Inc. 165 Examples You are converting a 640x350 IBM EGA PCX image called ega.pcx (which has an aspect ratio of 35:48) to a TIFF image and you want the TIFF image to have the correct aspect ratio value (so that an intelligent TIFF reader will correctly interpret the image). Note that the value of 73 is (35/48)*100: alchemy ega.pcx -D 73 -t The resulting image will still be 640x350, but the TIFF file now contains the information that the pixels are not square (and in fact are 35:48). If you had instead wanted to convert the image to a 640 by 480 image (with square pixels) you could have used: alchemy ega.pcx -Y480 -D100 -t The -D option isn't really needed here, since any software reading the TIFF file will assume that if there is no aspect ratio specified the pixels are square. 166 Copyright (c) 1990-1994 Handmade Software, Inc. Specify Image Resolution -D Purpose Specify image resolution in dots per inch for the output image. Syntax -D dotsPerInchX dotsPerInchY Parameters dotsPerInchX: The resolution of the image in the X direction in dots per inch. dotsPerInchY: The resolution of the image in the Y direction in dots per inch. Comments You must specify both dotsPerInchX and dotsPerInchY, even if they are the same. When converting from a raster file this command does not actually change the resolution of the image, it just adds the resolution fields to the output image. This is important when trying to import the image into software which expects this information. For example, Microsoft Word is much more likely to give the expected results when importing a TIFF image for printing on a laser printer if the image has a resolution of 300 dpi. Reasonable values to use for dotsPerInch include 72 (the resolution of a 13 inch monitor displaying 640x480) and 300 (the resolution of most laser printers). To write an output image without resolution information specify a resolution of 0 0 (zero zero). Alchemy will preserve this information when converting files whenever possible. Many file types do not have an resolution value; specifying one when writing such a file type will only affect the raster scaling functions. This option also has an effect when using the MS- DOS version of Image Alchemy and displaying images. Copyright (c) 1990-1994 Handmade Software, Inc. 167 Limitations It is not possible to specify both an aspect ratio and a dots per inch value for an image. This is because specifying a dots per inch value automatically implies an aspect ratio. This option is ignored when writing a file format which does not have image resolution. Related options -D Specify aspect ratio Examples Convert the Targa file input.tga to a TIFF file called output.tif, specifying that the resolution of the image in the TIFF file is 300 dpi by 300 dpi: alchemy input.tga output -t -D 300 300 Convert the file scan.tif to a DCX variation of a PCX file, scaling the output image to 1500 by 750 (preserving the image's aspect ratio) and setting the resolution to 200 DPI by 100 DPI (this is useful if you will be faxing the image using a fax card): alchemy scan.tif -p1 -X1500 -Y750 -+ -D 200 100 168 Copyright (c) 1990-1994 Handmade Software, Inc. 8 Viewing Options MS-DOS Only ------------------------------------------------------------------------ Display hardware Image Alchemy can display images on properly equipped MS-DOS based computers. Depending on the hardware you have installed, Alchemy supports the following display resolutions: 640x480, 800x600, 1024x768, and 1280x1024. Also depending on the hardware, Alchemy supports the following display depths: 8 bit, 15 bit, 16 bit, and 24 bit (for 256, 32768, 65536, and 16,777,216 colours, respectively). In addition, Alchemy supports the standard VGA mode of 320x200x256, the quasi-standard VGA mode of 360x480x256, and the common SVGA mode of 640x400x256. When instructed to display an image, Alchemy automatically detects which type of display board you have installed. If there are multiple display boards installed in your computer then Alchemy will display images on the first board it finds, searching in the following order: Western Digital based 8514/A board AI compatible 8514/A board XGA board VESA compatible SVGA board Other SVGA board Western Digital 8514/A boards which are equipped with the Western 8514/A Digital chipset are automatically recognized by Alchemy. Depending on the model board and the amount of memory installed, 640x480x256, 1024x768x256, and 1280x1024x256 modes are available. Copyright (c) 1990-1994 Handmade Software, Inc. 169 AI 8514/A Alchemy requires AI to be installed to use 8514/A displays which aren't based on the Western Digital chipset. In addition to 8514/A boards Alchemy should also be able to display on other AI compatible boards, such as 340x0 based boards; however this has not been tested. For AI based boards the only resolution available is 1024x768x256. XGA Alchemy automatically detects the presence of an XGA or XGA2 board and will use it when displaying images. The display modes available for XGA boards are 640x480x256, 1024x768x256, and 640x480x65536 (the actual modes available vary with the model XGA board installed and the amount of memory available). VESA The best support for SVGA boards is available for VESA compatible SVGA boards. VESA is an SVGA standard which allows application software, such as Image Alchemy, to interrogate the SVGA board to determine which display modes are available. Some SVGA boards have VESA support built directly into the BIOS found on the board; in this case Alchemy will automatically detect the VESA driver and use it. Other SVGA boards require a software driver to be installed; these drivers are usually found on the floppy disks which came with your SVGA board (typically the driver is called VESA.EXE). If you can't find a driver on the diskettes and the documentation does not explicitly mention that VESA support is built into the BIOS you might call the manufacturer to see if a VESA driver is available. VESA drivers are currently available for VGA boards using chipsets from Cirrus Logic, ATI Technologies, Chips and Technologies, Everex Systems, Genoa Systems, Paradise Logic, Sigma Designs, STB Systems, Tecmar, Headland Technology (Video 7), Orchid Technology, Appian Technology, Trident Microsystems, and Oak Technology. 170 Copyright (c) 1990-1994 Handmade Software, Inc. Other SVGA If Alchemy cannot find a VESA SVGA board it attempts to determine what kind of SVGA board is present. If Alchemy can identify the type of SVGA board installed either a 640x400x256 or 640x480x256 mode will be available. SVGA boards which are known to work with Alchemy include Paradise, Tseng Labs 3000 & 4000, Video 7, Trident, and Everex chipset based VGA Boards. VGA The 320x200x256 mode is a standard IBM VGA mode and will work on all VGA boards. The 360x480x256 is a non-standard VGA mode which should also work on all VGA boards. Display Unless you explicitly specify a resolution after Resolution the view command, Alchemy automatically uses the lowest resolution mode which will display the entire picture. Alchemy can be told to not use above a particular resolution by setting the environment variable alchemy to the largest horizontal resolution to be used. For example, if your monitor can only display up to 800x600 pixels, but your VESA compatible VGA board can display up to 1024x768 pixels. You would set alchemy=800, to insure that Alchemy won't try to use the 1024x768 mode. You may want to add this command to your autoexec.bat file, so that it is automatically set when your computer is turned on. When an image is displayed that is smaller than the screen resolution the image will be centered in the display and the area around the image will be set to the darkest colour in the image (which is usually black). Copyright (c) 1990-1994 Handmade Software, Inc. 171 Offset View -_ Purpose The offset view option changes the position of the image on the screen during viewing. Syntax -_ xOffset yOffset (underscore) Parameter xOffset: Number of pixels to shift the image horizontally. yOffset: Number of pixels to shift the image vertically. Examples View moving the image up 100 pixels: alchemy madonna.gif -v -_ 0 -100 View moving the image to the right 200 pixels and down 50 pixels: alchemy madonna.gif -v -_ 200 50 172 Copyright (c) 1990-1994 Handmade Software, Inc. View Image -v Purpose View file. Syntax -v horizontalResolution Parameter horizontalResolution: 320:Use 320x200 mode 360:Use 360x480 mode 640:Use 640x480 mode 800:Use 800x600 mode 1024:Use 1024x768 mode 1280:Use 1280x1024 mode Comments If displaying on a Western Digital chipset 8514/A or VESA compatible VGA board, an optional parameter may follow the -v command. This parameter specifies horizontal resolution and may be 320, 360, 640, 800, 1024, or 1280. The default is to use the lowest resolution which can fit the entire image. You may set the environment variable alchemy to indicate the highest horizontal resolution you want Alchemy to use when displaying images (for example, set alchemy=800 to will cause Alchemy to use only 640x480 and 800x600 resolutions when displaying images). If the image is true colour, a uniform palette will be used and the image will be dithered (dithering may be disabled by use of the -d option, see above). See Appendix B, Colour and Dithering, for more information. Related options -V Reduce image to fit display Example View the image madonna.gif: alchemy madonna.gif -v Copyright (c) 1990-1994 Handmade Software, Inc. 173 View Image in True Colour Mode --v Purpose View file using 15, 16, or 24 bits/pixel mode. This allows true colour images to be viewed without dithering to a uniform palette. Syntax --v horizontalResolution Parameter horizontalResolution: 640:Use 640x480 mode 800:Use 800x600 mode 1024:Use 1024x768 mode 1280:Use 1280x1024 mode Comments Requires a VESA compatible SVGA board or a Tseng 4000, S3, ATI, Genoa, Speedstar24, or a Speedstar24X with an appropriate DAC and at least 1 Megabyte of memory on the SVGA board. Resolutions above 640x480 are only supported by SVGA boards with a VESA driver. 640x480 mode is supported for various SVGA boards with sufficient memory and the correct DAC. Alchemy automatically picks the highest colour resolution which will fit the image you are trying to view. For example, if your SVGA boards supports 800x600x15 bit and 640x480x24 bit, Alchemy will use the 640x480x24 bit mode when viewing images which are 640x480 and smaller and the 800x600 mode when viewing larger images. You can of course override this by giving Alchemy a resolution parameter after the view command (for example, --v 640, to view in 640x480x24 bit mode). You may also set the environment variable alchemy to indicate the highest horizontal resolution you want Alchemy to use when displaying images (for example, set alchemy=800 to will cause Alchemy to use only 640x480 and 800x600 resolutions when displaying images). If the image being displayed is a 24 bits per pixel true colour image, and the display mode is 15 or 16 bits per pixel, the image will be dithered (dithering may be disabled by use of the -d option, see above). Example View madonna.tga: alchemy madonna.tga --v 174 Copyright (c) 1990-1994 Handmade Software, Inc. View Scaled Image -V Purpose View image while scaling image to fit on monitor and correcting aspect ratio. Syntax -V horizontalResolution Parameter horizontalResolution: 320:Use 320x200 mode 360:Use 360x480 mode 640:Use 640x480 mode 800:Use 800x600 mode 1024:Use 1024x768 mode 1280:Use 1280x1024 mode Comments If displaying on a Western Digital chipset 8514/A or VESA compatible VGA board, an optional parameter may follow the -v command. This parameter specifies horizontal resolution and may be 320, 360, 640, 800, 1024, or 1280. The default is to use the lowest resolution which can fit the entire image. You may set the environment variable alchemy to indicate the highest horizontal resolution you want Alchemy to use when displaying images (for example, set alchemy=800 to will cause Alchemy to use only 640x480 and 800x600 resolutions when displaying images). This command will scale the image and correct the aspect ratio of the image by removing rows and/or columns from the image. Note that this option can also be useful for displaying images which are not larger than the screen but which have an aspect ratio different than the display. Limitations Alchemy assumes that the aspect ratio of a display pixel is 1:1 when in 640x480, 800x600, 1024x768, and 1280x1024 modes, 5:6 when in 640x400 mode and 320x200 modes, and 16:9 in 360x480 mode. If not otherwise specified by using the -D option or in the file, Alchemy assumes that the aspect ratio of pixels in 640x400 images and 320x200 images is 5:6 and the aspect ratio of pixels in 640x350 images is 35:48. You can override any of these assumptions with the -D option. Copyright (c) 1990-1994 Handmade Software, Inc. 175 Don't worry if this is confusing; in practice Alchemy deals with everything automatically if you use the -V option. However, there is a problem with displaying 320x400 IFF files; see Appendix A, Answers to Frequently Asked Questions, for more information. Related options -D Specify image resolution -v View image Example View madonna.gif: alchemy madonna.gif -V 176 Copyright (c) 1990-1994 Handmade Software, Inc. View Scaled Image in True Colour Mode --V Purpose View image in 15 bit mode while scaling image to fit on monitor and correcting aspect ratio. Syntax --V horizontalResolution Parameter horizontalResolution: 640:Use 640x480 mode 800:Use 800x600 mode 1024:Use 1024x768 mode 1280:Use 1280x1024 mode Comments Requires a Tseng 4000, S3, ATI, Genoa, or Speedstar24 or an appropriate VESA compatible SVGA board with an appropriate DAC and 1 Megabyte of memory on the SVGA board. Resolutions above 640x480 are only supported by SVGA boards with a VESA driver. 640x480 mode is supported for various SVGA boards with sufficient memory and the correct DAC. Alchemy automatically picks the highest colour resolution which will fit the image you are trying to view. For example, if your SVGA board supports 800x600x15 bit and 640x480x24 bit, Alchemy will use the 640x480x24 bit mode when viewing images which are 640x480 and smaller and the 800x600 mode when viewing larger images. You can of course override this by giving Alchemy a resolution parameter after the view command (for example, --v 640, to view in 640x480x24 bit mode). You may also set the environment variable alchemy to indicate the highest horizontal resolution you want Alchemy to use when displaying images (for example, set alchemy=800 will cause Alchemy to use only 640x480 and 800x600 resolutions when displaying images). If the image being displayed is a 24 bits per pixel true colour image, and the display mode is 15 or 16 bits per pixel, the image will be dithered (dithering may be disabled by use of the -d option, see above). This command will scale the image and correct the aspect ratio of the image by removing rows and/or columns from the image. Copyright (c) 1990-1994 Handmade Software, Inc. 177 Note that this option can also be useful for displaying images which are not larger than the screen but which have an aspect ratio different than the display. Limitations The same limitations as for scaled 8 bit viewing apply (see above). Related options -D Specify image resolution --v View image in True colour mode Example View big.jpg in true colour 640x480 mode, reducing the image to fit on the screen: alchemy big.jpg --V 640 178 Copyright (c) 1990-1994 Handmade Software, Inc. 9 Tutorial and Examples ------------------------------------------------------------------------ Introduction This section gives a sample session of using Image Alchemy. It is assumed that you have installed Alchemy as instructed by the installation section of the manual. The sample image file, sample.jpg, which can be found in the \samples directory on the distribution disk or tape, must be in the current directory. Several of the examples include viewing commands. Viewing is not possible on non-MS-DOS versions of Image Alchemy (and viewing requires the installation of a compatible SVGA board). Examples We will use the sample.jpg image supplied in the \samples directory. The first step is to copy this into the directory with Alchemy. copy samples\sample.jpg . (cp samples/sample.jpg . for UNIX systems) Now we will convert this JPEG file to a GIF file. Notice that we don't have to specify an output file name. Alchemy will automatically generate the name sample.gif. alchemy sample.jpg -g We can then view this GIF file using Image Alchemy (assuming you have a compatible SVGA card): alchemy sample.gif -v To convert the sample.gif file to a PCX file called test1.pcx do the following: alchemy sample.gif test1.pcx -p You can now view this file by doing: alchemy test1 -v Copyright (c) 1990-1994 Handmade Software, Inc. 179 Note here that Alchemy automatically added the extension .pcx since none was supplied. Let us now convert the test1.pcx file to a small TIFF file called test1.tif; we will scale the TIFF file to be 200x100 pixels. To perform the scaling we will use -X and -Y options: alchemy test1.pcx -t -Xb200 -Yb100 In this case we specified that Alchemy should use type B scaling. This is a good scaling type to use for general purpose scaling (type A scaling is faster but not as good a quality, whereas Type C and Type D scaling are better quality but slower). You can now view this TIFF file by using: alchemy test1.tif -v If you had wanted to view it using the standard VGA mode 320x200 you could have used: alchemy test1.tif -v320 To convert this TIFF file to a gray-scale PCX file use alchemy test1.tif -b -p -o The -b option indicates black and white and the -o option tells Alchemy that it is okay to overwrite the existing test1.pcx file. You can now view this PCX file by using: alchemy test1.pcx -v To convert the JPEG file sample.jpg to a Targa file called sample.tga use the following command: alchemy -a sample.jpg To convert the 24 bit Targa file sample.tga to a 256 colour GIF file called new.gif: alchemy -g sample.tga new.gif To convert the 256 colour GIF file, new.gif, to a 64 colour PCX file called new.pcx: alchemy -p -c64 new.gif To view the GIF file new.gif (only applicable on IBM PCs with appropriate SVGA board): 180 Copyright (c) 1990-1994 Handmade Software, Inc. alchemy -v new.gif To convert sample.jpg to a black and white, two colour GIF file use a text editor to create a file called BW.PAL which contains the following: PAL 2 0 0 0 255 255 255 then: alchemy -g sample.jpg -f bw.pal (Alternatively, you could have said alchemy -g sample.jpg -b -c2, but that wouldn't have demonstrated the -f option). To view the resulting file in 320x200x256 mode, scaling the image to fit the display: alchemy -V320 sample.gif To create an LZW compressed TIFF file called new.tif which is 320x240 from the Targa file created earlier, using good quality scaling: alchemy sample.tga -t1 -Xb320 -+ new.tif Copyright (c) 1990-1994 Handmade Software, Inc. 181 182 Copyright (c) 1990-1994 Handmade Software, Inc. A Answers to Frequently Asked Questions ------------------------------------------------------------------------ Question When I view a JPEG compressed image on my VGA board it looks much worse than when I first convert it to a GIF file and then view it. Why is this? Answer To save time Alchemy automatically uses a uniform palette when you are just viewing a true colour image. When converting to a different file format Alchemy uses Heckbert quantization to generate a palette. The difference in image quality is the difference between using a uniform palette and an optimum palette. See Appendix B, Colour and Dithering, for more information on palette generation. Question Why is decompressing or compressing a JPEG image so slow? Answer There are a large number of calculations that have to be done during JPEG compression. This is an inherent limitation of JPEG compression. Image Alchemy has been optimized quite a bit to reduce the number of calculations, and we are working to further reduce the number of calculations. If you are transferring files over modems or storing them on slow media (tape) the compression times are usually more than made up for by the decrease in transmission or retrieval times. Copyright (c) 1990-1994 Handmade Software, Inc. 183 Question I'm using Alchemy to print an image. The print out is much darker than the original image. Why is this? Answer Many hard copy output devices, including laser printers, ink jet printers, and ink jet plotters, have a property known as dot gain. Dot gain causes more toner or ink to be placed on the paper than is expected. This is caused by the fact that the individual pixels being output are round, and in order to completely fill in a square grid with round pixels the round pixels have to be larger than the square (in fact the circle has π/2 times as much area as the square). In this example of a single pixel the black area represents the "extra" toner or ink that is being printed: You can compensate for dot gain by adjusting the gamma of the image during the conversion process. The exact gamma value will depend on the output device, but in general, specifying an output gamma of 2.0 produces good results (-Gi 1.0 -Go 2.0 on the command line will accomplish this). (If you are using a UCR file you can also compensate for dot gain by using a UCR file with a gamma of 2.0). It is not as necessary to compensate for dot gain when printing at a resolution less than the printer's maximum resolution. This is because the output device automatically groups individual pixels together to make the output pixel, which reduces the amount of extra toner or ink being deposited on the page, as in this example of printing a 150 DPI pixel on a 300 DPI device: The same is true if you are using dithering types 20 and 22 (since those dithering types cluster the dots). 184 Copyright (c) 1990-1994 Handmade Software, Inc. Question How do I capture screens when running in Microsoft Windows (or on the Macintosh)? Answer To capture the current screen when running Microsoft Windows press PRINT SCREEN. This copies a bitmap of the entire screen onto the clipboard. Then open the Paintbrush program which comes with Windows and select Paste to copy the image from the clipboard. The image may now be saved as a BMP file which Alchemy can convert. On the Macintosh press Command-Shift-3. This will create a file on your hard disk called Picture n, where n is a number which starts at 1 and increases by 1 every time you capture another screen. This file can be converted by Alchemy. Question Why can't my favorite desktop publishing package read the TIFF file I wrote with Image Alchemy? Answer TIFF is an extremely versatile standard; it can handle anything from 1 bit images to full colour images with an alpha channel. Also, TIFF allows many different types of compression. Unfortunately this versatility means that it's difficult for a single piece of software to be able to read in every valid TIFF file. If the software specifies the classes of TIFF it can read, you can force Alchemy to write out a specific TIFF class by using the following options: class B:-8 -b -c2 -t2 class G:-8 -b -t1 class P:-8 -t1 class R:-24 -t1 Class B is black and white, Class G is gray-scale, Class P is paletted, and Class R is true colour. Copyright (c) 1990-1994 Handmade Software, Inc. 185 If the supported classes are not specified, experiment with various combinations of -24, -8, - b, and -c. In this case it is usually best to use no compression (-t0) while experimenting with the other options, as many TIFF readers have difficulty with compressed files. When you find a set of options that work, then you can try various compression modes to save space. Be aware that using the -b option will force the output file to be gray-scale and you will lose the colour information in the file (most desktop publishing programs only have support for gray-scale TIFF files). You may also have to use the -Dn n option to specify the resolution of the image (this is especially true when converting from a file format which does not have a value for image resolution). You can generally tell if this is necessary because the program you are using to read in the TIFF file will claim that the file is unreasonably large or small. Usually, if you are using a 300 DPI Laser Printer you want to make the TIFF file 300 DPI x 300 DPI (-D 300 300). If you would like further information specific to using Image Alchemy with your word processor or desktop publishing program please contact us; we will be maintaining a list of how to make Alchemy work with other software packages. Similarly if you figure out how to import files into a specific package let us know and we will add your tips to our documentation. Question Why can't my paint package read the Targa file I wrote with Image Alchemy? Answer Some software which reads Targa files cannot handle compressed files. In addition, some software can read true colour Targa files, but cannot read paletted or gray-scale files. Image Alchemy can be forced to write out a true colour file by using the -24 option. 186 Copyright (c) 1990-1994 Handmade Software, Inc. Question When I convert a GIF file to a JPEG file and then back to a GIF file the final GIF file is twice the size of the original. Why is this? Answer There are two things which might cause this to happen: JPEG compression doesn't really work well for images which have large areas which are all the same colour. The reason for this is that JPEG is a lossy compression technique. Therefore you are not going to get back exactly the same values for each pixel in an area that was one solid colour before being JPEG compressed. But GIF compression works much better on areas which are one solid colour, so, when you GIF compress these areas, they are quite a bit larger than they were before. The solution to this problem is to use HSI JPEG compression, which automatically detects large areas of solid colours and does not JPEG compress them. The problem with HSI JPEG compression is that it isn't compatible with JPEG or JFIF. The other possibility is that the input GIF file didn't have very many different colours. When you converted it to a JPEG file the number of colours in the file was lost (JPEG gray-scale files always use 256 shades, and JPEG colour files are always true colour). When the JPEG file was converted back to a GIF file Alchemy assumed you wanted 256 colours in the file, and a 256 colour GIF file is bigger than a 16 colour GIF file. To prevent this you can use a -c32 (or however many colours the original had) option in the command line; this forces Image Alchemy to use that many colours for the output file. Question I keep getting "Out of Memory trying to ..." messages. Help! Answer Image Alchemy is running out of memory. If you are running on an IBM PC you can use alch386 instead of alchemy to do the conversion (if you were running alch386 when you received this error please contact us). If you are running one of the UNIX versions of Alchemy this message indicates that you are running out of swap space. Contact your system administrator to find out how you can increase the size of your swap space. Copyright (c) 1990-1994 Handmade Software, Inc. 187 Question I am using Alchemy to display a 320x400 IFF image created by an Amiga. When I use just the -v option the image comes out tall and skinny. When I use the -V option, which is supposed to correct the aspect ratio, things get worse instead of better (the image is even skinnier). What's going on? Answer As near as we can tell, some Amiga software has a different idea of what aspect ratio is than the rest of the world. For displays, aspect ratio is defined as the ratio of the width of a single pixel to the height of a single pixel. So if you have square pixels (which you do on a standard monitor in 640x480 mode) the aspect ratio is 1 to 1 (commonly written as 1:1). When you change display modes the height and width of the total display area does not change; what is changing is the width and height of each pixel, which means that the aspect ratio changes. For example, a 640x400 display has an aspect ratio of 1:1.2 (that means each pixel is 1.2 times as tall as it is wide (which makes sense since 480/400 equals 1.2)). A 640x200 display has an aspect ratio of 1:2.4. Now this is where it gets interesting in terms of IFF files. The aspect ratio number stored in Amiga IFF files for 320x400 images is 1:1.1, meaning pixels are 1.1 times as tall as they are wide, so therefore the actual image should be the equivalent size of a 320x440 image with square pixels. And this is what Alchemy will attempt to display when you use the -V option (Alchemy never makes any dimension larger, so the actual image Alchemy displays is 291x400, which is the same ratio as 320x440). However this is obviously wrong, as you can tell when you examine an image. As near as we can tell the correct aspect ratio of these images is 5:3 (the math we used to come up with this number is 640/320:480/400). And if you tell Alchemy to override the aspect ratio by using a -D 167 option (167 because 5/3*100 is 166.6666) the image displays correctly. Why Amigas create images which claim they are 1:1.1 remains a mystery. 188 Copyright (c) 1990-1994 Handmade Software, Inc. Question I told Alchemy to convert a PCX file to an 8 bit GIF file (using the -8 option). Yet when I get statistics on the file (using -x) Alchemy reports the file only has 16 colours. Answer Alchemy will always store the file using the smallest bits-per-pixel allowable for the given image (this results in the smallest possible file). In this case the input file only had 16 colours in it. Things get more unpredictable with formats such as Sun Raster (which requires 1 bit files to be black and white) and SGI (which requires 8 bit files to be gray-scale). In these cases Alchemy will always do the best it can (giving you a warning message if it does something which may surprise you later). Question I've converted a Mac PICT file to a GIF file, but the GIF file is missing some or all of the information that was in the PICT file. What happened to it? Answer PICT files are a combination of drawing commands (such as lines, rectangles, and circles) and raster areas (called pixMaps). Alchemy can only read the raster portions of the files. Programs such as MacDraw and MacDraft write out files with drawing commands, programs such as MacPaint write out files which are entirely raster areas (pixMaps), and some programs, such as SuperPaint can write out files which are either, or a combination of both. If you are using such a program check the documentation on how to write out files in "paint" mode. Copyright (c) 1990-1994 Handmade Software, Inc. 189 Question Why can't Image Alchemy read in JPEG files produced by Kodak's ColorSqueeze (or Sun's VFCtool)? Answer The JPEG standard is still in draft form. Until it is a mature standard, various manufacturers will implement different versions of it. As of March 1, 1991 Image Alchemy supports the JFIF format and should work with any other JPEG software which also claims JFIF compatibility. If other software you are using claims to support the JFIF format and you are having trouble, please contact us. If the other software does not support JFIF, contact the manufacturer and tell them they should send you an update which does (you can tell them to contact us if they need a copy of the JFIF standard). Question When I convert a 32 bit Targa file to a GIF file and then to a JPEG file it doesn't look nearly as good as if I convert the Targa File directly to the JPEG file. What can I do to maintain high quality in JPEG compressed files? Answer When the Targa file was converted to the GIF file Image Alchemy had to reduce the number of colours in the file (the original Targa File had up to 16 million colours, GIF files are limited to 256 colours). This step is known as colour quantization (Image Alchemy uses the Heckbert Median Cut method for quantization; see Appendix B, Colour and Dithering, for more information). The difficulty with colour quantization is that it leaves artifacts known as colour banding. To reduce this phenomenon Image Alchemy dithers the image (you can see the effect of colour banding by turning off dithering by using the -d0 option). Unfortunately a dithered image does not JPEG compress very well (dithering adds a lot of high- frequency information to an image; JPEG compression attempts to remove much of that information). In addition JPEG images are always continuous colour images, so when the JPEG file is decompressed it has to be colour quantized and dithered again. Dithering a previously dithered image reduces the quality even more. The solution is to use the best starting quality you can for JPEG compression, ideally a continuous tone image. The compressed image size will be smaller than if you had started with a paletted image and the quality will be better. 190 Copyright (c) 1990-1994 Handmade Software, Inc. Question I've converted an HP PCL file to a GIF file, but the GIF file is missing some or all of the information that was in the PCL file. What happened to it? Answer PCL files have the same problem as PICT files (see above); they are a combination of drawing commands (such as lines and rectangles) and raster areas (called rasters) and Alchemy can only convert the raster areas in PCL files. PCL Files also contain font and text information, which is also lost. Unfortunately there isn't any general way to preserve this data with Alchemy. One thing which you can do if running Microsoft Windows 3.0 is to install Adobe Type Manager (ATM). ATM automatically intercepts any text commands and converts them to rasters. In addition, the standard Windows 3.0 HP PCL driver only generates rasters, not vectors. So the file will appear in its entirety when converted by Alchemy. Contact us if you want further information on using Alchemy with Windows. Question I converted a PCX file with 16 colours to a 16 shades of gray TIFF file using the -b and -t options. The 16 colour PCX file had some shades of gray in it which were changed in the TIFF file. How can I prevent this? Answer The problem is that gray-scale TIFF files have a uniformly spaced gray palette. If you create a TIFF file with 16 shades of gray it will have the following shades in it: 0, 17, 34, 51, 68, 85, 102, 119, 136, 153, 170, 187, 204, 221, 238, and 255. However the 16 colour PCX file you started with probably didn't have those exact colours in it (for example, PCX files written out by Windows 3.0 Paint have shades of gray which correspond to 0, 128, 192, and 255). So Alchemy did the best it could and matched the input colours to the output colours (and depending on the other options that you specified may also have dithered the image). Copyright (c) 1990-1994 Handmade Software, Inc. 191 The solution is to tell Alchemy to write out a 256 colour gray-scale TIFF file (which you do by adding a -c256 to the -b and -t options). This file still has a uniform gray palette; but that palette now contains every colour: 0, 1, 2, 3, ..., 255. Therefore Alchemy can map, for example, the colours 128 and 192 to their exact match. This does have the disadvantage of making the resulting 256 colour TIFF file twice as large as the 16 colour TIFF file, but this is the only way to guarantee that Alchemy can find an exact match for all the shades of gray in the input file. Question How do I get a copy of the current draft JPEG standard? Answer The JPEG standard is an ISO/IEC standard currently in Committee Draft form. Contact your local ISO/IEC office to get a copy. The reference numbers are ISO/IEC JTC 1 and /SC 2 N2215; the document number is ISO/IEC CD 10918-1. In the United States you can contact ANSI at: ANSI 11 West 42nd St. New York, NY 10036 (212) 642-4900 Question Do you give multiple copy discounts? Do you have site licenses? Are you interested in licensing the source code? Answer Yes. Yes. Yes. Contact us for more information. 192 Copyright (c) 1990-1994 Handmade Software, Inc. B Colour and Dithering ------------------------------------------------------------------------ Paletted vs. Colour images are normally stored in one of two true colour ways: as an array of direct colour values (usually red, green, and blue) (referred to as a true colour file in this document) or as an array of indices into a colour-map which contains red, green, and blue colour values (referred to as a paletted file in this document). Paletted images exist because they take less memory, so the hardware to display them is less expensive. The dominance of paletted hardware is changing as the price of memory and the processing power it takes to update large amounts of memory at a reasonable speed drops (a Targa 32 board is an example of a true colour board, a standard VGA board is an example of a paletted board). Until true colour graphics devices become the norm, there is a need to convert images from true colour to paletted. This conversion is done in two steps: the first is to generate a palette for use by the image; the second is to map the image to the new palette. Colour cube The colour model generally used by computers is a cube with red, green, and blue as the axes (this is known as a colour cube or RGB cube). Each point inside the cube is a different colour, depending on the amount of red, green, and blue used. In nature each of the three axes is nearly continuous, therefore there are a nearly infinite number of colours available. Computer hardware and software represent colours in a discrete fashion. For true colour displays or file formats the number of discrete positions along each axis of the colour cube gives the colour resolution of the output device. For example, a Targa 24 board for an IBM PC has 8 bits per red, green, and blue channel for a total of 24 bits (or 256 discrete shades of each colour, for a total of 16 million colours (256x256x256)). This is also the colour resolution of most true colour file formats. Copyright (c) 1990-1994 Handmade Software, Inc. 193 A 15 bit SVGA boards has 5 bits per channel, for a total of 32x32x32 different colours (32,768). This is the same colour resolution as a Targa 15 file. A paletted display or image file has the same colour resolution limit as a true colour display or image file, but in addition there is a limit on how many points inside the cube can be used at the same time. An 8 bit file format, such as GIF, allows 256 different colours out of 16 million. A non-true-colour SVGA board also only allows 256 different colours at one time. So, converting a true colour file to a paletted file involves reducing the number of occupied points in the colour cube. There are several ways this can be done. Generating a Image Alchemy supports two methods of generating a palette palette: Uniform palettes The simplest and fastest method is to use a palette containing colours which are uniformly distributed in the RGB cube, this is referred to as a uniform palette. This has the advantage that it's fast and the same palette can be used for any image; the primary disadvantage is that most images don't contain colours from everywhere in the RGB cube, so palette entries are wasted representing colours that aren't needed for the particular image being converted. 194 Copyright (c) 1990-1994 Handmade Software, Inc. Optimal palettes To generate a palette which is better for representing a particular image, Image Alchemy supports Heckbert's median cut algorithm. This algorithm first builds a three dimensional table (a histogram cube) indicating how popular any given colour in the RGB cube is in the image being converted. It then proceeds to subdivide this histogram cube (by dividing boxes in half) until it has created as many boxes as there are palette entries. The decision as to where to divide a box is based on the distribution of colours within the box. This algorithm attempts to create boxes which have approximately equal popularity in the image. Palette entries are then assigned to represent each box. There are other methods of generating a palette from an image, but Heckbert's algorithm is generally regarded as the best tradeoff between speed and quality. Modifying the You can change the method used to select a colour palette selection to represent each box by use of the -z options. process The default method is to use the mean of all the colours in the box. However for some images slightly better results can be obtained by using the center of the box (without regard to where the pixels are in the box). For images being reduced to a very small number of colours (less than 16) better results can be obtained by using a corner of the box (the boxes tend to be large when reducing an image to a small number of colours; therefore picking colours near the centers of the boxes will give you muddy colours, while using corners of the boxes will give you saturated colours). And having saturated colours allows the dithering algorithms to generate better looking images. Mapping the image The next step is to map the image to the new to the palette palette; this is where dithering becomes important. No dithering The simplest approach is to map every colour in the original image to the palette entry which is closest to it (this is what Image Alchemy does if you specify no dithering). Copyright (c) 1990-1994 Handmade Software, Inc. 195 However, since the palette entries generally represent several different colours in the original image, this results in colour banding where areas of smooth colour changes in the original become areas of one solid colour in the paletted version. Advantages of This can be alleviated by dithering the image data dithering such that any given pixel might not be mapped to its closest palette entry, but the average over some area of the image will be closer to the correct colour than it would otherwise be. Image Alchemy uses a class of algorithms called "error- diffusion" to do dithering. Error diffusion These algorithms work by using the closest palette dithering entry to a colour and then distributing the error (the difference between the desired colour and the chosen palette entry) to the nearby pixels. This process is repeated for every pixel in the image, using the colour values which have been modified due to the error from previous pixels. The different dithering algorithms spread the error over a different area or use a different weighting within the same area. Serpentine raster Error diffusion can be done as a normal raster (left to right, top to bottom) or as a serpentine raster (alternating left to right and right to left, top to bottom). A serpentine raster tends to break up visible patterns introduced by dithering. Noise Random noise can also be added to help break up visible patterns in the resulting image. Further For more information on Heckbert's median cut and information dithering see the appropriate reference listed in the References section below. 196 Copyright (c) 1990-1994 Handmade Software, Inc. C What is JPEG Compression? ------------------------------------------------------------------------ Who are those JPEG stands for the "Joint Photographic Experts JPEG guys? Group". This is a group of experts who defined a standard compression scheme for still images, commonly called JPEG Compression. Currently the standard is still in draft form. Overview JPEG Compression consists of a series of complex mathematical operations, including: colour space conversion, discrete cosine transforms, quantization, and entropy coding. After these steps you end up with an image which takes fewer bits to store than you started out with. However, when you decompress a JPEG compressed image you end up with an image that is not quite the same as the original (which is why JPEG Compression is referred to as "lossy"). Is lossy You might well ask why anyone would want to compression bad? compress an image using a lossy technique. Compression ratios for lossy compression are much better than for lossless compression and the loss is generally very small. And, in fact, every operation of converting an image is lossy (the original photographic or electronic process which captured the image was lossy, scanning or digitizing the image was lossy, displaying the image on a monitor is lossy, and printing the image is lossy). Details JPEG compression involves the following steps: Step 1 The image is converted to a colour space with separate luminance and chrominance channels. This is done because the human eye is far more sensitive to the luminance information (Y) than it is to the chrominance information (Cb and Cr); by separating them, it's possible to compress the chrominance information more than the luminance before the perceived image quality suffers. Copyright (c) 1990-1994 Handmade Software, Inc. 197 This step isn't specified in the JPEG draft (it doesn't discuss colour space at all), but is standard practice. Image Alchemy uses CCIR-601 YCbCr, which is the colour space specified by the JFIF standard. Step 2 The luminance and chrominance information are separately transformed to the frequency domain using a discrete cosine transform acting on 8x8 pixel blocks. To reduce the amount of data which needs to be compressed the chrominance information may be sub- sampled first. Alchemy uses 2h:1v:1h:1v:1h:1v sub-sampling when writing JPEG files, which means that the first component (luminance) has twice as many samples horizontally as the other two components (chrominance), and the same number of samples vertically. Alchemy can read JPEG files with any sub-sampling allowed by the draft standard. Step 3 The transformed data is quantized (so some information is thrown away). The samples representing higher frequencies are generally quantized using larger steps than those representing low frequencies. The quality level you specify is used to scale a set of quantization values which have been found to cause the quantized data to all have approximately equal importance visually. A lower quality number will cause larger quantization steps to be used, and hence increase the compression ratio and decrease the image quality. Step 4 The quantized data is compressed using an entropy coder. Huffman and Arithmetic coding are allowed by the draft JPEG standard; only Huffman coding is allowed by the JFIF standard. Huffman coding can either be done with a set of fixed tables or custom tables can be generated for an image. Alchemy, by default, uses a fixed set of tables, but can also generate custom tables which usually produce 5-20% (depending on the image and quality setting) better compression. However, producing custom tables requires an additional pass over the image data and therefore takes a little longer. 198 Copyright (c) 1990-1994 Handmade Software, Inc. JPEG Interchange This data corresponds to the JPEG Interchange Format Format and is ready to be stored in a file. Unfortunately the JPEG Interchange Format does not include enough information to actually be able to convert the file back to an image. Specifically the colour space used and the aspect ratio or resolution of the image are not included. Until recently there was no standard way of putting this information in a JPEG file. JFIF On March 1, 1991 representatives of several JPEG hardware and software developers (including C- Cube, Radius, NeXT, Storm Tech., the PD JPEG group, Sun, and Handmade Software) met at C-Cube and established the JPEG File Interchange Format (JFIF). JFIF allows for the standardization of those pieces of information missing from the JPEG Interchange Format and therefore allows various software packages, by different vendors, to produce compatible JPEG files. If you would like more information on the JFIF standard please contact us. Copyright (c) 1990-1994 Handmade Software, Inc. 199 200 Copyright (c) 1990-1994 Handmade Software, Inc. D Customer Support ------------------------------------------------------------------------ Why might Alchemy We have made every effort to insure that Image mess up? Alchemy can read all files in its supported formats. However, because of poorly written standards and non-adherence to standards there are undoubtedly certain files that Image Alchemy does not read correctly. What we need to If you come across any files which Image Alchemy help you has trouble with, please contact us with as much of the following information as you have: version of Image Alchemy you are using, type of file, type of computer which generated it, name and version of software which wrote the file, size of image, and the number of colours in image. We may ask you to send us the file so that we can figure out what went wrong. If you send us a file we will attempt to modify Image Alchemy so that it can read the file. Once Alchemy is modified, we will send you an updated copy of it. Similarly, if any files that Image Alchemy writes cannot be read by other software please contact us. We may ask you to send us a copy of a file that can be read by that software package for comparison. Please contact us even if you are just using a demo copy of Alchemy. In addition to helping fix a bug, we feel the best way to get you to purchase a copy of Alchemy is to demonstrate how committed we are to customer support. Copyright (c) 1990-1994 Handmade Software, Inc. 201 How to contact us Our address and phone numbers are: Handmade Software, Inc. 48820 Kato Road, Suite 110 Fremont, CA 94538 800 358 3588 (Toll-free from within the U.S.) +1 510 252 0101 (Voice) +1 510 252 0909 (Fax) The most efficient way to contact us is by e-mail; this is especially true if you can send us a sample file which demonstrates the problem you are having. Please enclose a short note with your name and phone number so that we may call you if we need further information. Our e-mail addresses are: Internet: hsi@netcom.COM CompuServe: 71330, 3136 We also have a 24 hour bulletin board where you can upload and download files. It speaks 2400 baud, 9600 baud (v32, v42, and v42.bis), and PEP; its number is: +1 510 252 0929 (BBS) If you upload a file to our BBS please leave a short note to the SYSOP so that we know what the problem you are having is. We also have a fax-on-demand system which allows you to request and automatically receive faxes from your fax machine. Its phone number is: +1 510 252 0303 (fax-on-demand) 202 Copyright (c) 1990-1994 Handmade Software, Inc. E Binary Information Files (BIF) ------------------------------------------------------------------------ Overview Binary files are image files which are just data. In other words, they do not contain any information other than the actual pixels in the image file. In order to read these files you must create a file using a text editor which describes to Alchemy the format of the file you are trying to read in. This is called a BIF file (and typically has the extension .bif). Required At the minimum a BIF file needs to contain the information filename of the image data file and either the height or the width of the image. Alchemy will make assumptions about the other characteristics of the image based on the information that it is given and the total length of the image file. BIF file format The first line contains the letters BIF, which identifies the file as a BIF file. Each of the rest of the lines in the BIF file consist of an information tag followed by the information. The spelling of the tags must be exact or Alchemy will report an unknown tag error. Copyright (c) 1990-1994 Handmade Software, Inc. 203 Tags Tag Description filename The name of the file containing the binary data. width The width of the image data, in pixels. height The height of the image data, in pixels. planes The number of planes of image data (1, 2, 3, or 4). A 1 plane image is assumed to be gray-scale, a 2 plane image is a gray-scale image with an alpha channel, a 3 plane image is an RGB image, and a 4 plane image is an RGB image with an alpha channel. header The size of the header, in bytes. This many bytes are skipped when reading the file. leftpadding The number of bytes to remove from the beginning of each scan line. rightpadding The number of bytes to remove from the end of each scan line. order The order of the pixels. For 2 channels either ga or ag(g=gray, a=alpha). For 3 channel images, this can be any sequence of r, g, and b: rgb, rbg, grb, gbr, brg, or bgr (r=red, g=green, b=blue). For 4 channel images, this can be any sequence of a, r, g, and b (a=alpha). The defaults are g, ga, rgb, and rgba, depending on the number of planes. interleave The type of interleaving of the pixel data: 0: No interleave RGBRGBRGBRGBRGBRGB... 1: Line interleave RRR...GGG...BBB...RRR...GGG ...BBB... 2: Plane interleave RRRRRR...GGGGGG...BBBBBB... The default is 0, no interleave. upsidedown The presence of this tag indicates that the data in the file is recorded from the bottom of the screen up to the top of the screen. Comments Lines beginning with a # are treated as comments. Comments and blank lines are ignored when processing the BIF file. 204 Copyright (c) 1990-1994 Handmade Software, Inc. Palette files If the binary file has a palette available, you can use that palette by writing your own software to convert it to a .PAL file and using the -F option while reading the BIF file. Example This is an example BIF file which can be used to read a 640 pixel wide, true colour HSI Raw file. Note that HSI raw files have a 32 byte header which is being skipped. Of course you could read the Raw file directly using Alchemy, but this is after all an example of a BIF file. BIF width 640 #skip past header header 32 filename sample.raw planes 3 #the tags below aren't actually needed, #since rgb and non-interleave are #the default, but they are included #here to give an example of what those #tags looks like order rgb interleave 0 Using the example Assuming the BIF file is called sample.bif, the BIF file following Alchemy command can be used to convert the image to a GIF file: alchemy sample.bif -g The height of the image will be automatically calculated from the length of the file and the width, header, and planes tags. A BIF file is treated as an ordinary file, so all the standard Alchemy commands may be used with it. Copyright (c) 1990-1994 Handmade Software, Inc. 205 206 Copyright (c) 1990-1994 Handmade Software, Inc. F HSI Raw Files ------------------------------------------------------------------------ History The HSI Raw format was originally an internal format to Image Alchemy. Because of user demand the format has been documented to allow others to read and write HSI Raw files. Overview HSI Raw files are completely uncompressed, unpacked, and unpadded image data files. Therefore they tend to be larger than almost any compressed file format. However, they have the advantage, as far as Alchemy is concerned, that they are very fast to read and write and the location of any pixel in the image may be found by simple calculations. If you need to convert custom files to a format that Alchemy can read we recommend using a Raw file; it is the simplest format to write and the fastest for Alchemy to read. Variations There are two types of HSI Raw Files: paletted and true colour. Paletted images are stored one byte per pixel with a palette at the beginning of the file. True colour files are stored three bytes per pixel. Gray-scale Gray scale files are stored as paletted files with a palette that contains all gray values. Alchemy automatically recognizes such files during reading and will treat them appropriately. Black and white Black and White files are stored as paletted files with a palette that contains two values, black and white. Alchemy automatically recognizes such files during reading and will treat them appropriately. Warning Note that Handmade Software, Inc. reserves the right to make changes to this format at any time and without notice. And while it is unlikely, it is possible that future versions of Image Alchemy will not support this format. Copyright (c) 1990-1994 Handmade Software, Inc. 207 Old version files This appendix describes version 4 Raw files. This is the version that Image Alchemy has written since March 1991. Before this Alchemy wrote version 2 and 3 raw files (version 2 were 8 bit files, version 3 were 24 bit files). Those raw files can be read by current versions of Image Alchemy but are not otherwise supported. If you run across any of these raw files the easiest thing to do is to use a current copy of Alchemy to convert them to a version 4 raw file. Details Word size All values which are not otherwise identified are two byte integers (16 bits). This is the native integer size of most IBM PC C-compilers but not Macintosh and UNIX C-compilers. Byte order All integers are stored high byte first (big- endian order). This is the native mode for Macintosh's and Sun's but not the native mode for IBM PC's. See below for a CPU independent method to read and write 2-byte integers. Pixel format Paletted files are stored one byte per pixel. True colour files are stored as three bytes per pixel in red, green, blue order. Padding Neither the palette information nor the pixel data is padded to anything other than a byte boundary. This means that if you store a file which is 13 by 11 pixels it will occupy 429 bytes if stored as a true colour file (not including the header), or 143 bytes if stored as a paletted file (not including the header and palette data). Hex Numbers including a 0x prefix are hex; all other numbers are decimal. File format The header for a paletted file is 32 bytes plus the size of the palette. The header for a true colour file is exactly 32 bytes (a true colour file contains no palette). Magic number Six bytes used to identify the file as an HSI Raw file: 0x6d 0x68 0x77 0x61 0x6e 0x68 208 Copyright (c) 1990-1994 Handmade Software, Inc. Version An integer used to identify the version HSI file: 0x0004 Width An integer indicating the width of the image (in pixels). Height An integer indicating the height of the image (in pixels). Palette size An integer indicating the number of entries in the palette. Range is 2 to 256. A 0 or -24 indicates a true colour image (which has no palette data). Horizontal DPI An integer indicating the horizontal resolution of the image, in dots per inch. A zero indicates that the resolution is unknown. A negative number is used if only the aspect ratio is known. Vertical DPI An integer indicating the vertical resolution of the image, in dots per inch. A zero indicates that the resolution is unknown. A negative number is used if only the aspect ratio is known. Gamma An integer indicating the gamma of the image, scaled by 100 (a gamma of 2.2 is stored as 220). A zero indicates that the gamma is not known. Reserved Twelve bytes reserved for future use. Should be set to zero when writing. Palette The palette data is stored as 3 bytes per palette entry. The bytes are in red, green, blue order; 0 is black, 0xff is full intensity. True colour raw files have no palette. Image data The image data. Example files 8 bit paletted, 6D 68 77 61 6E 68 00 04 01 40 00 C8 01 00 00 00 320 x 200: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 49 24 24 24 00 00 00 00 00 DB 6D 6D FF 92 92 FF B6 B6 92 49 49 FF DB DB FF B6 92 FF FF DB FF DB B6 FF FF FF B6 6D 6D 6D 24 24 DB 92 6D 6D 49 49 ... Copyright (c) 1990-1994 Handmade Software, Inc. 209 24 bit true 6D 68 77 61 6E 68 00 04 01 40 00 C8 00 00 00 00 colour, 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 320 x 200: 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 49 24 24 ... Reading a two int getWord(int i, FILE *stream) { byte integer register int temp; temp=getc(stream)<<8; return(getc(stream) | temp); } Writing a two int putWord(int i, FILE *stream) { byte integer putc(i>>8, stream); return(putc(i&0xff, stream)); } 210 Copyright (c) 1990-1994 Handmade Software, Inc. G Undercolour Removal Files ------------------------------------------------------------------------ Summary Undercolour removal files are text files which control the conversion from RGB to CMYK colour space. This conversion consists of four steps. The first is to convert an RGB value to an ideal CMY value; this simply involves negating the RGB values. The next step is to determine how much black is in that colour; this is done by finding the minimum of the CMY values and using that as an index into the black removal portion of the Undercolour Removal tables documented below. These tables have independent values for how much black to use for that pixel and how much black to subtract from the CMY values. Next, a linear transform is optionally applied to the CMY portion of the CMYK pixel. Finally the CMYK values are optionally translated, independently, through the CMYK density correction tables (this last step is only used if the image is going to be dithered output on a 1 bit per pixel per component device). Copyright (c) 1990-1994 Handmade Software, Inc. 211 File format Black removal The first 256 non-comment lines contain tables undercolour removal values corresponding to computed black values of 0 (white) to 255 (black). Each of these lines has two numbers; the first indicates how much black to use in place of the computed black value corresponding to the line, and the second indicates how much black to subtract from the cyan, magenta, and yellow components (this value must not be greater than the corresponding computed black value). After the black removal block the remaining blocks may appear in any order. CMY linear If there is a line which says only "HSI CMY transform matrix" then the next 3 non-comment lines contain a matrix representing a linear transform which is applied to the cyan, magenta, and yellow components after black removal and before applying the density map. The entries are normalized around 256. The first row and column represent cyan, the second magenta, and the third yellow. The rows are multiplied by the input cyan, magenta, and yellow values to create the corrected values. A matrix of 256 0 0 0 256 0 0 0 256 is equivalent to omitting the matrix and causes no correction to take place. In this case it would be preferable to omit the matrix as the conversion will run slightly faster without it. CMYK density If there is a line which says only "HSI CMYK correction tables density map" then the next 256 non-comment lines contain density correction tables, corresponding to cyan, magenta, yellow, and black values of 0 (white) to 255. Each of these lines has four numbers representing, in order, the amount of cyan, magenta, yellow, and black to use in place of the corresponding computed values. These tables are only applied during dithering; they will not be used for those CMYK output formats which are continuous tone, as devices which take continuous tone input data should be doing their own correction. 212 Copyright (c) 1990-1994 Handmade Software, Inc. Comments Any line beginning with ';' is a comment and is ignored. Example The following undercolour removal file has undercolour removal tables, CMYK density correction tables, and a CMY colour correction matrix. ; Undercolour removal file ; 0 0 1 1 1 1 2 2 3 3 ... (256 entries total) 169 169 169 169 170 170 ; HSI CMY matrix ;the following matrix leaves the ; Cyan and Yellow planes alone, and ; subtracts a bit from the Magenta ; plane when there's Cyan present. ; 256 0 0 -32 256 0 0 0 256 ; HSI CMYK density map ; 0 0 0 0 0 0 0 0 0 0 0 0 ... (256 entries total) 248 248 248 248 251 251 251 251 253 253 253 253 255 255 255 255 Copyright (c) 1990-1994 Handmade Software, Inc. 213 214 Copyright (c) 1990-1994 Handmade Software, Inc. H PAL Files ------------------------------------------------------------------------ Overview PAL files are text files which contain a palette in an ASCII form. Alchemy can extract palettes from other file formats and write PAL files. Alchemy can also use PAL files when converting images. File format The first line contains the letters "PAL"; this identifies the file as a palette file. The next line contains an integer indicating the number of palette entries. Valid values are 2 through 256. The rest of the file consists of lines of 3 numbers, representing the red, green, and blue values for each of the colours. These have a range of 0 (black) to 255 (full intensity). Any information after the 3 numbers is treated as a comment and ignored. Example PAL 8 ;# colours 0 0 0 ;black 255 0 0 ;bright red 0 128 0 ;dark green 255 255 0 ;yellow 0 0 255 ;blue 255 0 255 ;magenta 63 63 63 ;gray 255 255 255 ;white Copyright (c) 1990-1994 Handmade Software, Inc. 215 216 Copyright (c) 1990-1994 Handmade Software, Inc. I Acknowledgments ------------------------------------------------------------------------ Summary Almost all the software which comprises Image Alchemy was written in house. However some of the modules are modifications of software originally written by other people or software that we've licensed. TIFF Image Alchemy's TIFF I/O is based on libtiff which is copyright by Sam Leffler and is used with his permission. If you are interested in reading or writing TIFF files we strongly suggest that you start with libtiff. Libtiff is available by anonymous ftp as ucbvax.berkeley.edu:pub/tiff/*.tar.Z or uunet.uu.net:graphics/tiff.tar.Z. If you cannot get a copy of libtiff via anonymous ftp please contact us for a free copy. LZW Compression The LZW compression method is the subject of United States patent number 4,558,302 and corresponding foreign patents owned by Unisys Corporation and the use of it for TIFF LZW compression is licensed from them. Further information on licensing this patent can be obtained from: Unisys Corporation Welch Licensing Department Office of the General Counsel M/S C1SW19 Blue Bell, PA 19424 VGA display The MS-DOS version of Image Alchemy's 640x400 SVGA display routines are based on VGAKIT, written by John Bridges. VGAKIT is available free of charge from a variety of bulletin boards If you cannot find VGAKIT locally please contact us for a free copy. Copyright (c) 1990-1994 Handmade Software, Inc. 217 Spawning The spawn function used by the MS-DOS GUI uses the SPAWNO routines by Ralf Brown to maximize the available memory while spawning Alchemy. For more information on SPAWNO contact: Ralf Brown 813 Copeland Way, Suite 26 Pittsburgh, PA 15232 +1 713 880 3059 internet: ralf+@cs.cmu.edu 218 Copyright (c) 1990-1994 Handmade Software, Inc. J Other Useful Software ------------------------------------------------------------------------ Summary There are several image processing packages available for free or as shareware. Please be aware that we mention these software packages only as a service to Image Alchemy users. We are not endorsing or recommending any particular package. Some of the packages are no longer supported by their authors. If you have trouble finding any of the listed software please send us a blank tape or diskette and we will send you a copy free of charge (please be aware that the software may be quite large; contact us first if you have any questions). If you know of any other software which would be appropriate to add to this list please let us know. If you are the author of any of these packages and you would rather not be on this list please let us know that also. IBM PC These programs are only available as executable code and can only be run under MS-DOS. PicLab A public-domain image file conversion and printing tool. Written by Lee Crocker and the Stone Soup Group. Available via CompuServe. Cshow A shareware image viewing program. Written by Bob Berry. Available from: Canyon State Systems and Software PO Box 86 Sedona, AZ 86336 Vivid A shareware ray-tracing program. Written by Stephen B. Coy Available from: Stephen Coy 15205 NE 13th Pl., #2904 Bellevue, WA 98007 Copyright (c) 1990-1994 Handmade Software, Inc. 219 Workstations These programs are only available as source code and generally require a workstation running UNIX or one of its variants. Utah Raster Written by Spencer W. Thomas, Rod G. Bogart, and Toolkit (URT) James Painter. Available via anonymous FTP as pub/urt-3.0.tar.Z via anonymous ftp from cs.utah.edu, weedeater.math.yale.edu, or freebie.engin.umich.edu. Fuzzy Bitmap Written by Michael Mauldin Manipulation Available by anonymous ftp as (FBM) nl.cs.cmu.edu:/usr/mlm/ftp/fbm.tar.Z, uunet.uu.net:pub/fbm.tar.Z, or ucsd.edu:graphics/fbm.tar.Z. Portable BitMap Written by Jef Poskanzer (PBMPLUS) Available by anonymous ftp as expo.lcs.mit.edu:contrib/pbmplus.tar.Z or ftp.ee.lbl.gov:pbmplus.tar.Z. Img Software Set Written by Paul Raveling Available by anonymous ftp as expo.lcs.mit.edu:contrib/img_1.3.tar.Z or venera.isi.edu:pub/img_1.3.tar.Z. 220 Copyright (c) 1990-1994 Handmade Software, Inc. Glossary ------------------------------------------------------------------------ Anonymous FTP An easy way to transfer files via the Internet. If you don't have Internet access you can't use anonymous FTP; if you do have Internet access you probably already know about it (if you don't, ask your system administrator or local network guru). Black and white An image which contains just two colours, black and white. Many file formats, such as TIFF and Sun Raster, have special variations for black and white images. You can force Alchemy to write a black and white image by specifying -b -c2 as options. Dithering A technique for reducing the amount of colour banding in an image when converting from a large number of different colours to a small number of different colours. Different dithering techniques are usually named after the person or persons who first invented them. Alchemy supports Floyd- Steinberg, Stucki, and JJN dithering; these are further described in "Digital Halftoning", by Robert Ulichney, MIT Press. Gray-scale An image which contains just shades of gray. Many file formats, such as TIFF and Silicon Graphics, have special variations for gray-scale images. You can force Alchemy to write a gray-scale image by specifying -b -8 as options. Header The portion of an image file that is not the actual image data. The data in a header generally includes the image size (in pixels), the image depth (in number of bits per pixel or number of colours), and the palette (if the image has a palette). Some file formats include quite a bit of additional data in the header, such as: the name of the image, the date and time the image was created, and the latitude and longitude of the image (primarily used by satellite image data). The header is called the header because it usually appears at the head of the file. Some file formats store information which is usually found in the header in a separate file. Copyright (c) 1990-1994 Handmade Software, Inc. 221 Heckbert colour A technique for reducing the number of colours quantization needed by an image, typically used to convert a true colour image to a paletted image. Named after Paul Heckbert who originally described the technique in "Color Image Quantization for Frame Buffer Display", SIGGRAPH '82 Proceedings, p. 297. Magic Number A number or sequence of numbers that is found at or near the start of an image file so that software may determine what type of format the file is. Most formats have a well defined magic number; some formats do not, in which case Alchemy examines various parameters in the header of the file and guesses what format the image is. Paletted An image which isn't true colour. Each pixel in the image is an index into a table of values (typically red, green, and blue) which describe the colour of that pixel. Most paletted images are limited to 8 bits of information, which allows 256 unique colours. Most display adapters only allow the display of paletted images (Alchemy can display true colour images on those display adapters by using a uniform palette). True colour An image which does not contain a palette. Each pixel in the image is represented by at least three values, typically red, green, and blue. True colour images are generally produced by scanners and digitizers and are better quality and much larger than paletted images. Most display systems cannot display true colour images. 222 Copyright (c) 1990-1994 Handmade Software, Inc. References ------------------------------------------------------------------------ General Computer Computer Graphics - Principles and Practice, Graphics Second Edition (Commonly referred to as Foley and van Dam) J.D. Foley, A. van Dam, S.K. Feiner, and J.F. Hughes Addison-Wesley ISBN 0-201-12110-7 Principles of Interactive Computer Graphics (Commonly referred to as Newman and Sproull) W.M. Newman and R.F. Sproull McGraw-Hill ISBN 0-07-046338-7 Algorithms for Graphics and Image Processing Theo Pavlidis Computer Science Press ISBN 0-914894-65-X Graphics Gems Andrew S. Glassner Academic Press ISBN 0-12-286165-5 Graphics Gems II James Arvo Academic Press ISBN 0-12-064480-0 Image Lab Tim Wegner Waite Group Press ISBN 1-878739-11-5 Copyright (c) 1990-1994 Handmade Software, Inc. 223 Specific Topics Colour The Reproduction of Colour in Photography, Printing & Television R.W.G. Hunt Fountain Press ISBN 0 85242 356 X Dithering Digital Halftoning Robert Ulichney MIT Press. ISBN 0-262-21009-6 File Formats Graphics File Formats David C. Kay and John R. Levine Windcrest/McGraw-Hill ISBN 0-8306-3060-0 Bit-Mapped Graphics Steve Rimmer Windcrest ISBN 0-8306-3558-0 Supercharged Bit-Mapped Graphics Steve Rimmer Windcrest/McGraw-Hill ISBN 0-8306-3788-5 JPEG JPEG Still Image Compression Standard William B. Pennebaker and Joan L. Mitchell Van Nostrand Reinhold ISBN 0-442-01272-1 Image Scaling Digital Image Warping George Wolberg IEEE Computer Society Press Monograph ISBN 0-8186-8944-7 PDF (Portable Portable Document Format Reference Manual Document Format) Adobe Systems Incorporated Addison-Wesley ISBN 0-201-62628-4 224 Copyright (c) 1990-1994 Handmade Software, Inc. PostScript PostScript Language Reference Manual, Second Edition Adobe Systems Incorporated Addison-Wesley ISBN 0-201-18127-4 Adobe Type 1 Font Format, Version 1.1 Adobe Systems Incorporated Addison-Wesley ISBN 0-201-57044-0 VGA Programming Programmer's Guide to the EGA and VGA Cards, Second Edition Richard F. Ferraro Addison-Wesley ISBN 0-201-57025-4 Copyright (c) 1990-1994 Handmade Software, Inc. 225 226 Copyright (c) 1990-1994 Handmade Software, Inc.